# General Translation Python SDKs: 快速入门
URL: https://generaltranslation.com/zh/docs/python/quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 安装 General Translation Python SDK，并为你的第一个 Flask 或 FastAPI 应用添加翻译。

General Translation Python SDK 可为 Flask 和 FastAPI 应用中的面向用户的字符串提供翻译。你只需在应用中初始化一次，然后在路由中用 [`t`](/docs/python/reference/functions/t) 函数包装字符串，它就会将其翻译为当前请求的区域设置。

为你使用的框架安装对应的集成：Flask 使用 `gt-flask`，FastAPI 使用 `gt-fastapi`。两者都基于共享的 `gt-i18n` Runtime 构建，你也可以在非框架项目中直接使用它。

<Callout type="warn">
  Python SDK **仍处于实验阶段且不稳定**。`gt-i18n`、`gt-flask` 和 `gt-fastapi` 仍处于早期开发阶段，并且在各个 release 之间可能会有破坏性变更。它要求 Python 3.10 或更高版本。
</Callout>

## Python SDK 的作用 [#overview]

该 SDK 提供：

* 使用 [`t`](/docs/python/reference/functions/t) 进行**字符串翻译**，并支持 ICU 消息语法。
* 从 `Accept-Language` header 检测**按请求的区域设置检测**，或使用你自己的逻辑。
* 通过 [`derive`](/docs/python/reference/functions/derive) 处理**有限变体**，并通过 [`declare_var`](/docs/python/reference/functions/declare-var) 处理不可翻译的值。
* 通过 **CDN 或本地方式交付**由 [General Translation CLI](/docs/cli/quickstart) 生成的翻译。

## 快速入门 [#quickstart]

安装该集成，添加配置文件，在你的应用中完成初始化，并翻译一个字符串。

### 1. 安装集成组件

<Tabs items={['Flask', 'FastAPI']}>
  <Tab value="Flask">
    ```bash
    pip install gt-flask
    ```
  </Tab>

  <Tab value="FastAPI">
    ```bash
    pip install gt-fastapi
    ```
  </Tab>
</Tabs>

### 2. 配置你的区域设置

在项目根目录下创建 `gt.config.json`，填入你的项目 ID 和 locales。各个键的说明请参阅[配置参考](/docs/python/reference/config)。

```json title="gt.config.json"
{
  "projectId": "your-project-id",
  "defaultLocale": "en",
  "locales": ["es", "fr"]
}
```

使用占位符 `projectId` 时，应用仍然可以运行，请求区域设置也仍然会变化，但所有字符串都会以源语言返回。在你设置自己的项目 ID 并发布翻译之前，这都是预期行为。

### 3. 在应用中初始化

在启动时调用一次 `initialize_gt(app)`。它会读取 `gt.config.json`、注册按请求的区域设置检测，并预加载翻译。无需传入 API Key 参数——CDN 加载使用 `project_id` 和 `cache_url`。

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

    app = Flask(__name__)
    initialize_gt(app)

    @app.route("/")
    def index():
        return {"message": t("Hello, world!"), "locale": get_locale()}
    ```

    使用以下命令运行：

    ```bash
    flask --app app run
    ```
  </Tab>

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

    app = FastAPI()
    initialize_gt(app)

    @app.get("/")
    def index():
        return {"message": t("Hello, world!"), "locale": get_locale()}
    ```

    FastAPI 需要单独的 ASGI 服务器。安装 Uvicorn 并使用以下命令启动应用：

    ```bash
    pip install "uvicorn[standard]"
    uvicorn main:app
    ```
  </Tab>
</Tabs>

### 4. 使用变量翻译

使用 ICU 占位符，并以关键字参数形式传入值。

```python
t("Hello, {name}!", name="Alice")
```

### 5. 生成翻译

在部署前，使用 [General Translation CLI](/docs/cli/quickstart) 翻译你的内容，以便在运行时提供翻译。CLI 是一个 Node 工具，因此需要先安装 Node，并通过 `npx` 运行。

```bash
npx gt translate
```

## 不使用框架时使用核心库 [#core]

如果你没有使用 Flask 或 FastAPI，请直接安装 `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) 将其注册，并自行设置请求的区域设置。

```bash
pip install gt-i18n
```

```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!"))
```

 (有关上下文和变量，请参阅[翻译字符串](/docs/python/guides/translating-strings)；如需自定义区域设置检测，请参阅[检测请求的区域设置](/docs/python/guides/detecting-locale)) 。

## 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.