# General Translation Python SDKs: initialize_gt
URL: https://generaltranslation.com/zh/docs/python/reference/functions/initialize-gt.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: initialize_gt 的 API 参考。为 Flask 或 FastAPI 应用配置一次 General Translation Python SDK。

为 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`。两者的函数签名完全一致。core library 中没有 `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` 钩子；在 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)       | 源区域设置和后备内容。            | `str`                                                                 | 是  | 配置，其次为 `"en"`     |
| [`locales`](#locales)                     | 支持的目标区域设置。             | `list[str]`                                                           | 是  | 配置                |
| [`custom_mapping`](#custom-mapping)       | 自定义区域设置代码和属性覆盖。        | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | 是  | 配置                |
| [`project_id`](#project-id)               | 项目 ID；设置后会启用 CDN 加载器。  | `str`                                                                 | 是  | 配置                |
| [`cache_url`](#cache-url)                 | 覆盖 CDN 基础 URL。         | `str`                                                                 | 是  | 配置                |
| [`version_id`](#version-id)               | 已固定的翻译版本。              | `str`                                                                 | 是  | 配置                |
| [`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]` · **可选** · **默认值** 配置值

要支持的目标区域设置。优先解析为传入的参数；否则解析为 `gt.config.json` 中的 `locales` 数组。默认区域设置始终包含在管理器的区域设置集合中。

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

**类型** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **可选** · **默认配置值**

用于将自定义区域设置代码映射到标准代码或属性覆盖。请参阅 [`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]

**类型** `str` · **可选** · **默认值** 为配置值

要加载的固定版本翻译。对应配置中的 `_versionId` 键，并由 [`get_version_id`](/docs/python/reference/functions/get-version-id) 返回。

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

**类型** `(request) -> str` · **可选** · **默认** 解析 `Accept-Language`

用于自定义区域设置检测的回调函数。它接收 request 并返回一个区域设置代码，完全取代内置的 `Accept-Language` 检测。若返回假值，则会使用默认区域设置。

```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 在 locale-source 方面差异的说明，请参阅[工作原理](#how-it-works)。

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

**类型** `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
# 显式指定 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.