# General Translation Python SDKs: t
URL: https://generaltranslation.com/ja/docs/python/reference/functions/t.mdx
---

title: t
description: Python で General Translation を使用して ICU MessageFormat 文字列を翻訳・補間します。t の API リファレンス。

---

ICU MessageFormat 文字列を、現在のリクエストで有効なロケールに翻訳し、補間します。`t` は、ユーザーが直接使用する主要な翻訳関数です。

## 概要 [#overview]

`t` にソース文字列と任意の補間変数をキーワード引数として渡します。現在のロケール向けに翻訳・補間された文字列を返し、翻訳が見つからない場合は補間済みの原文を返します。

```python
from gt_flask import t  # または: from gt_fastapi import t、または: from gt_i18n import t

message = t("Hello, {name}!", name="World")
```

シグネチャ:

```python
t(message: str, **kwargs: object) -> str
```

*注: `t` はアクティブな manager を参照するため、[`initialize_gt`](/docs/python/reference/functions/initialize-gt) (または [`set_i18n_manager`](/docs/python/reference/functions/set-i18n-manager)) を先に実行する必要があります。そうしないと `RuntimeError` が発生します。*

## 仕組み [#how-it-works]

* **ロケールの確認。** manager から現在のロケールを取得します。そのロケールで翻訳が不要な場合 (たとえばデフォルトロケールと同じ場合) は、検索をスキップし、原文の補間のみを行います。
* **ハッシュ検索。** それ以外の場合は、メッセージ (`_context`、`_id`、`_max_chars` を含む) をハッシュ化し、そのロケール向けのキャッシュ済み翻訳をインメモリキャッシュから取得します。キャッシュは同期的に動作するため、翻訳は事前に読み込まれている必要があります。詳しくは [eager loading](/docs/python/guides/configuring#preload) を参照してください。
* **補間。** 翻訳が見つかった場合は、ICU MessageFormat を使って補間されます。このとき、指定した変数を使用し、宣言された `_gt_` 変数を解決するための `__fallback` として原文を使います。
* **フォールバック。** 翻訳が見つからない場合は、原文の文字列を補間して返します。

## パラメーター [#parameters]

| パラメーター                | 説明                           | 型       | 任意  | デフォルト |
| --------------------- | ---------------------------- | ------- | --- | ----- |
| [`message`](#message) | ICU MessageFormat のソース文字列です。 | `str`   | いいえ | —     |
| [`kwargs`](#kwargs)   | 補間変数と GT の予約済みオプションです。       | キーワード引数 | はい  | —     |

### `message` [#message]

**Type** `str` · **必須**

翻訳および補間の対象となる ICU MessageFormat のソース文字列。

### `kwargs` [#kwargs]

**型** キーワード引数 · **任意**

ICU のプレースホルダーに対応する補間変数に加えて、以下の GT の予約済みオプションも指定できます。これらは補間から除外され、メッセージハッシュに組み込まれます。

* `_context` (`str`) — 同じ source text を持つ翻訳の意味を区別するための追加コンテキスト。
* `_id` (`str`) — 翻訳エントリ用のカスタム識別子。
* `_max_chars` (`int`) — 出力に適用される最大文字数。

*名前が 1 つのアンダースコアで始まるユーザー変数 (たとえば `_name`) は、引き続き補間変数として扱われます。予約されているのは上記の 3 つのキーだけです。*

## 戻り値 [#returns]

**型** `str`

翻訳と補間が適用された文字列、または翻訳が利用できない場合は補間済みの原文です。

## 例 [#examples]

```python
# シンプルな翻訳
t("Hello, world!")
```

```python
# 変数を使用する場合
t("Hello, {name}!", name="Alice")
```

```python
# 同一のソーステキストを区別するためにcontextを使用する
t("Bank", _context="financial institution")
t("Bank", _context="river bank")
```

```python
# f-stringとdeclare_varを使用する場合 — 動的な値をラップして保持する
from gt_flask import t, declare_var

# i18n適用前:
message = f"{name} goes home"

# i18n適用後 — t()とdeclare_var()でラップする:
message = t(f"{declare_var(name, name='name')} goes home")
```

```python
# 文字数制限を設ける場合
t("This is a very long message that might need truncation", _max_chars=20)
```