# General Translation Python SDKs: 配置 General Translation
URL: https://generaltranslation.com/zh/docs/python/guides/configuring.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 介绍如何在 Python 中初始化 General Translation，包括应用、区域设置，以及 Flask、FastAPI 或核心库中的翻译传递。

Python SDK 只需一次调用即可完成配置。在 Flask 和 FastAPI 中，调用方式为 `initialize_gt(app)`；而在核心 `gt-i18n` 核心库 中，则需要你自行构建 [`I18nManager`](/docs/python/reference/classes/i18n-manager)。本指南将介绍这两种方式，以及翻译的传递与预加载。

## 配置 Flask 或 FastAPI 应用 [#framework]

在开始处理请求之前，调用一次 `initialize_gt(app)`。它会读取 `gt.config.json`、创建翻译管理器、注册针对每个请求的区域设置检测，并预加载翻译内容。

<Tabs items={['Flask', 'FastAPI']}>
  <Tab value="Flask">
    ```python title="app.py"
    from flask import Flask
    from gt_flask import initialize_gt

    app = Flask(__name__)
    initialize_gt(app, default_locale="en", locales=["es", "fr"])
    ```
  </Tab>

  <Tab value="FastAPI">
    ```python title="main.py"
    from fastapi import FastAPI
    from gt_fastapi import initialize_gt

    app = FastAPI()
    initialize_gt(app, default_locale="en", locales=["es", "fr"])
    ```
  </Tab>
</Tabs>

关键字参数会覆盖 `gt.config.json` 中的设置。所有选项和配置键请参阅[配置参考](/docs/python/reference/config)。

这两个集成共用相同的 [`initialize_gt`](/docs/python/reference/functions/initialize-gt) 签名；只有内部实现不同。Flask 会注册一个 `before_request` 钩子来设置区域设置；FastAPI 会包装应用生命周期 (用于预加载) ，并添加一个用于设置区域设置的 HTTP 中间件。

## 配置核心库 [#core]

核心 `gt-i18n` 包不提供 [`initialize_gt`](/docs/python/reference/functions/initialize-gt)。请创建一个 [`I18nManager`](/docs/python/reference/classes/i18n-manager)，使用 [`set_i18n_manager`](/docs/python/reference/functions/set-i18n-manager) 将其注册为当前活动管理器，并自行设置请求的区域设置。这里不会自动执行区域设置检测或预加载。

```python
from gt_i18n import I18nManager, set_i18n_manager, t

manager = I18nManager(default_locale="en", locales=["es", "fr"])
set_i18n_manager(manager)

manager.set_locale("es")   # 每个请求的区域设置由你自行控制
print(t("Hello, world!"))
```

任何翻译函数 ([`t`](/docs/python/reference/functions/t)、[`get_locale`](/docs/python/reference/functions/get-locale) 等) 都会从通过 [`set_i18n_manager`](/docs/python/reference/functions/set-i18n-manager) 设置的管理器读取。在设置管理器之前调用其中任何一个，都会引发 `RuntimeError`。

## 选择翻译的传递方式 [#delivery]

SDK 会通过以下其中一种模式解析翻译：

* **General Translation CDN：**设置 `project_id` (在配置中或作为关键字参数传入) ，这样翻译会从 `{cache_url}/{project_id}/{locale}` 的 CDN 加载。你也可以用 `cache_url` 覆盖基础 URL。
* **本地文件：**传入一个 `load_translations` 回调函数，为某个区域设置返回 `dict[str, str]`。这会覆盖 CDN 加载器。请参阅[在本地存储翻译](/docs/python/guides/storing-translations)。

无需 API 密钥。CDN 传递完全由 `project_id` 和 `cache_url` 决定。

## 预加载翻译 [#preload]

[`t`](/docs/python/reference/functions/t) 函数会从内存缓存中读取翻译，因此必须在请求使用翻译前完成加载。默认情况下，[`initialize_gt`](/docs/python/reference/functions/initialize-gt) 会在启动时预加载翻译 (`eager_loading=True`) 。

*注意：只有在已知目标 `locales` 时，才会执行预加载。在 Flask 中，系统会直接检查传递给 [`initialize_gt`](/docs/python/reference/functions/initialize-gt) 的 `locales`，而不会检查从 `gt.config.json` 加载的 `locales`。如果区域设置仅来自配置文件，请显式传入，或自行加载翻译。如果翻译尚未加载，[`t`](/docs/python/reference/functions/t) 会返回源字符串。*

*注意：内存缓存会在 `cache_expiry_time` 后过期 (默认 60 秒) ，而 [`t`](/docs/python/reference/functions/t) 使用的同步读取路径不会重新加载缓存。缓存过期后，[`t`](/docs/python/reference/functions/t) 会回退到源字符串，直到异步加载器再次运行。[`initialize_gt`](/docs/python/reference/functions/initialize-gt) 未提供 `cache_expiry_time` 配置项。*

## 处理缺失的翻译 [#missing]

当缺少翻译时，[`t`](/docs/python/reference/functions/t) 会返回用你的变量插值后的源字符串，而不是抛出错误，因此请求始终可以正常渲染。请在部署前通过 [CLI](/docs/cli/quickstart) 生成翻译，确保生产环境已准备好这些翻译。

## Next steps

- /docs/python/guides/translating-strings
- /docs/python/guides/detecting-locale
- /docs/python/guides/declaring-variables
- /docs/python/guides/storing-translations

## Sitemap

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