# General Translation Python SDKs: initialize_gt
URL: https://generaltranslation.com/ja/docs/python/reference/functions/initialize-gt.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Flask または FastAPI アプリ向けに General Translation Python SDK を一度だけ設定します。initialize_gt の API リファレンス。

Flask または FastAPI アプリ向けに General Translation を設定します。起動時に `initialize_gt` を一度だけ、ほかの翻訳関数より前に呼び出して、翻訳マネージャーを構築し、リクエストごとのロケール検出を登録して、翻訳の配信を設定します。

## 概要 [#overview]

アプリを渡して `initialize_gt` を呼び出します。設定は現在の作業ディレクトリにある `gt.config.json` から読み込まれ、キーワード引数が指定されている場合はその値でファイル内の値が上書きされます。設定済みの [`I18nManager`](/docs/python/reference/classes/i18n-manager) を返し、同時にそれをアクティブなマネージャーとして登録するため、後続の [`t`](/docs/python/reference/functions/t) の呼び出しやロケールヘルパーが自動的に機能します。

```python
from flask import Flask
from gt_flask import initialize_gt

app = Flask(__name__)
initialize_gt(app)
```

シグネチャ：

```python
initialize_gt(
    app,
    *,
    default_locale: str | None = None,
    locales: list[str] | None = None,
    custom_mapping: CustomMapping | None = None,
    project_id: str | None = None,
    cache_url: str | None = None,
    version_id: str | None = None,
    get_locale: Callable[..., str] | None = None,
    load_translations: Callable[[str], dict[str, str]] | None = None,
    eager_loading: bool = True,
    config_path: str | None = None,
    load_config: Callable[[str | None], GTConfig] | None = None,
) -> I18nManager
```

使用しているフレームワークに応じて、`gt_flask` または `gt_fastapi` から `initialize_gt` をインポートします。シグネチャはどちらも同じです。コアライブラリには `initialize_gt` はありません。フレームワークを使わない場合は、代わりに [`I18nManager`](/docs/python/reference/classes/i18n-manager) を作成して [`set_i18n_manager`](/docs/python/reference/functions/set-i18n-manager) を呼び出します。

*注: `api_key` パラメータはありません。CDN 配信は `project_id` と `cache_url` によって制御されます。*

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

* **設定の解決。** 設定は (`load_config`、明示的な `config_path`、またはデフォルトの `gt.config.json` を通じて) 読み込まれ、その後、各設定はキーワード引数、設定値、ライブラリのデフォルト値の順に解決されます。
* **マネージャーのセットアップ。** 解決済みの設定を使って [`I18nManager`](/docs/python/reference/classes/i18n-manager) を構築し、[`set_i18n_manager`](/docs/python/reference/functions/set-i18n-manager) で登録します。
* **ロケール検出。** Flask では `before_request` hook を登録します。FastAPI では HTTP ミドルウェアを追加し、アプリの lifespan をラップします。各リクエストでは、[`get_locale`](/docs/python/reference/functions/get-locale) が指定されていればその値から、そうでなければ `Accept-Language` header からロケールを設定します。
* **事前読み込み。** `eager_loading` が true でターゲットロケールが判明している場合、すべての翻訳をあらかじめ読み込みます。Flask では、直接渡した `locales` 引数 (設定にのみ存在する locales ではなく) を確認します。FastAPI では、ラップされた lifespan 内で、解決済みのロケールに対して実行されます。

## パラメータ [#parameters]

| パラメータ                                     | 説明                                  | 型                                                                     | 任意  | デフォルト             |
| ----------------------------------------- | ----------------------------------- | --------------------------------------------------------------------- | --- | ----------------- |
| [`app`](#app)                             | Flask または FastAPI のアプリケーションインスタンス。  | `Flask \| FastAPI`                                                    | いいえ | —                 |
| [`default_locale`](#default-locale)       | source と fallback locale。           | `str`                                                                 | はい  | Config、次に `"en"`  |
| [`locales`](#locales)                     | サポートされているターゲットロケール。                 | `list[str]`                                                           | はい  | Config            |
| [`custom_mapping`](#custom-mapping)       | カスタムのロケールコードとプロパティの 上書き。      | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | はい  | Config            |
| [`project_id`](#project-id)               | プロジェクト ID。設定すると CDN ローダー が有効になります。 | `str`                                                                 | はい  | Config            |
| [`cache_url`](#cache-url)                 | CDN ベース URL の 上書き。            | `str`                                                                 | はい  | Config            |
| [`version_id`](#version-id)               | 固定する翻訳バージョン。                        | `str`                                                                 | はい  | Config            |
| [`get_locale`](#get-locale)               | カスタムの ロケール検出 コールバック。                | `(request) -> str`                                                    | はい  | `Accept-Language` |
| [`load_translations`](#load-translations) | 指定したロケールの翻訳を返すカスタム ローダー。            | `(locale: str) -> dict[str, str]`                                     | はい  | —                 |
| [`eager_loading`](#eager-loading)         | 起動時にすべての翻訳を事前に読み込みます。               | `bool`                                                                | はい  | `True`            |
| [`config_path`](#config-path)             | `gt.config.json` ファイルのパス。           | `str`                                                                 | はい  | `gt.config.json`  |
| [`load_config`](#load-config)             | デフォルトの設定ローダーを置き換えるカスタム ローダー。        | `(path: str \| None) -> GTConfig`                                     | はい  | —                 |

### `app` [#app]

**型** `Flask | FastAPI` · **必須**

設定対象のアプリケーションインスタンスです。位置引数として渡し、それ以外のパラメータはすべてキーワード引数でのみ指定します。

### `default_locale` [#default-locale]

**型** `str` · **任意** · **デフォルト** 設定値、次に `"en"`

コンテンツが記述されているソースロケールであり、翻訳が見つからない場合のフォールバックとしても使われます。引数、`gt.config.json` の `defaultLocale`、`"en"` の順に解決されます。

### `locales` [#locales]

**型** `list[str]` · **任意** · **デフォルト** config の値

サポートするターゲットロケールです。引数が指定されていればその値が使われ、そうでない場合は `gt.config.json` の `locales` 配列が使われます。デフォルトロケールは常にマネージャー のロケールセットに含まれます。

### `custom_mapping` [#custom-mapping]

**型** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **任意** · **デフォルト** config の値

カスタムのロケールコードを標準コードまたはプロパティの上書きに対応付けるマッピングです。[`customMapping`](/docs/python/reference/config#custom-mapping)を参照してください。

### `project_id` [#project-id]

**型** `str` · **任意** · **デフォルト** 設定値

General Translation のプロジェクト IDです。これを設定すると (`load_translations` が指定されていない場合) 、`{cache_url}/{project_id}/{locale}` から CDN 翻訳を読み込めるようになります。

### `cache_url` [#cache-url]

**型** `str` · **任意** · **デフォルト** 設定値

翻訳の読み込みに使用する CDN のベース URL を上書きするための設定です。General Translation の CDN は `https://cdn.gtx.dev` です。

### `version_id` [#version-id]

**Type** `str` · **省略可能** · **デフォルト** 設定値

読み込む翻訳バージョンを固定して指定します。`_versionId` 設定キーに対応しており、[`get_version_id`](/docs/python/reference/functions/get-version-id) によって返されます。

### `get_locale` [#get-locale]

**型** `(request) -> str` · **任意** · **デフォルト** `Accept-Language` のパース

カスタムのロケール検出コールバックです。リクエストを受け取り、ロケールコードを返して、組み込みの `Accept-Language` 検出を完全に置き換えます。falsy な値が返された場合は、デフォルトロケールに解決されます。

```python
def get_locale(request):
    return request.args.get("lang") or "en"

initialize_gt(app, get_locale=get_locale)
```

### `load_translations` [#load-translations]

**型** `(locale: str) -> dict[str, str]` · **任意**

CDN ではなく独自のソースから、指定したロケールの翻訳を読み込むカスタム関数です。指定した場合、CDN ローダーより優先されます。同期関数でも、awaitable を返す関数でもかまいません。

```python
def load_translations(locale: str) -> dict[str, str]:
    # 独自のソースから翻訳を読み込む
    ...

initialize_gt(app, load_translations=load_translations)
```

### `eager_loading` [#eager-loading]

**型** `bool` · **任意** · **デフォルト** `True`

true の場合、すべての翻訳は初回使用時ではなく、起動時に読み込まれます。Flask と FastAPI におけるロケールとソースの違いについては、[動作の仕組み](#how-it-works) の注記を参照してください。

### `config_path` [#config-path]

**Type** `str` · **任意** · **デフォルト** `gt.config.json`

`gt.config.json` ファイルへのパスです。デフォルトでは、現在の作業ディレクトリにある `gt.config.json` が使用されます。明示的に指定したパスが存在しない場合は、`FileNotFoundError` が発生します。

### `load_config` [#load-config]

**型** `(path: str | None) -> GTConfig` · **省略可**

デフォルトのファイルローダーの代わりに使用するカスタム設定ローダーです。`config_path` を受け取り、`GTConfig` の `dict` を返します。

## 戻り値 [#returns]

**型** [`I18nManager`](/docs/python/reference/classes/i18n-manager)

設定済みの[`I18nManager`](/docs/python/reference/classes/i18n-manager)で、アクティブなマネージャーとしてすでに登録されています。

## 例 [#examples]

```python
# 最小限のセットアップ。gt.config.json を読み込む
from flask import Flask
from gt_flask import initialize_gt

app = Flask(__name__)
initialize_gt(app)
```

```python
# カスタム translation ローダー を使用して locales を明示的に指定する
from fastapi import FastAPI
from gt_fastapi import initialize_gt

app = FastAPI()

def load_translations(locale: str) -> dict[str, str]:
    # 独自のソースから翻訳を読み込む
    ...

initialize_gt(app, default_locale="en", locales=["es", "fr"], load_translations=load_translations)
```

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.