# General Translation Python SDKs: 配置
URL: https://generaltranslation.com/zh/docs/python/reference/config.mdx
---

title: 配置
description: 通过 gt.config.json 文件配置 General Translation Python SDK。gt.config.json 的 API 参考。

---

`gt.config.json` 包含 General Translation Python 项目的共享设置。[`initialize_gt`](/docs/python/reference/functions/initialize-gt) 会在启动时读取该文件 (或者你也可以将其中的值传给 [`I18nManager`](/docs/python/reference/classes/i18n-manager)) ，你传入的任何关键字参数都会覆盖文件中的值。本页说明了 SDK 会读取的每个键。

*注意：Python SDK 目前仍处于实验阶段。*

## 概览 [#overview]

将 `gt.config.json` 放在项目根目录中 (默认是当前工作目录；可通过 `initialize_gt(..., config_path=...)` 覆盖) 。文件中的键均使用 **camelCase**。所有键都是可选的；无法识别的键会被忽略。如果默认文件不存在，则使用空配置——但如果显式指定的 `config_path` 不存在，则会引发 `FileNotFoundError`；JSON 无效则会引发 `ValueError`。

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

| 键                                  | 描述                    | 类型         | 可选 | 默认值    |
| ---------------------------------- | --------------------- | ---------- | -- | ------ |
| [`projectId`](#project-id)         | 项目 ID；设置后会启用 CDN 加载器。 | `string`   | 是  | —      |
| [`defaultLocale`](#default-locale) | 源区域设置和后备区域设置。         | `string`   | 是  | `"en"` |
| [`locales`](#locales)              | 支持的目标区域设置代码。          | `string[]` | 是  | —      |
| [`cacheUrl`](#cache-url)           | 用于加载翻译的 CDN 基础 URL。   | `string`   | 是  | —      |
| [`customMapping`](#custom-mapping) | 自定义区域设置代码和属性覆盖。       | `object`   | 是  | —      |
| [`_versionId`](#version-id)        | 锁定的翻译版本。              | `string`   | 是  | —      |
| [`runtimeUrl`](#runtime-url)       | 运行时 API 的基础 URL。      | `string`   | 是  | —      |

## `projectId` [#project-id]

**类型** `string` · **可选**

你的 General Translation 项目 ID。设置后 (且未提供 `load_translations` callback 时) ，SDK 会从 `{cacheUrl}/{projectId}/{locale}` 对应的 CDN 加载翻译。对应 `initialize_gt` 和 `I18nManager` 中的 `project_id` 参数。

## `defaultLocale` [#default-locale]

**类型** `string` · **可选** · **默认值** `"en"`

内容所使用的源区域设置，以及在找不到翻译时使用的后备区域设置。如果在配置和 `initialize_gt` 调用中都未设置，则会回退到库的默认值 `"en"` (即 `LIBRARY_DEFAULT_LOCALE` 常量) 。

## `locales` [#locales]

**类型** `string[]` · **可选**

要支持的目标区域设置。即使此处省略，默认区域设置也始终会包含在管理器的区域设置集中。预加载会在启动时获取这些区域设置的翻译。

## `cacheUrl` [#cache-url]

**类型** `string` · **可选**

用于构造翻译请求的 CDN 基础 URL (`{cacheUrl}/{projectId}/{locale}`) 。General Translation 的 CDN 地址为 `https://cdn.gtx.dev`。

*注意：未设置 `cacheUrl` 时，管理器当前会向远程加载器传入空的基础 URL，而不会使用默认的 CDN 值——如需通过 CDN 加载，请显式设置 `cacheUrl`。*

## `customMapping` [#custom-mapping]

**类型** `object` · **可选**

用于将自定义区域设置代码映射为标准代码，或映射为属性覆写 (例如 `{ "en-US": { "name": "English", "nativeName": "English" } }`) 。它对应 `custom_mapping` 参数以及 `generaltranslation` 中的 [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) 类型。

## `_versionId` [#version-id]

**类型** `string` · **可选**

要加载的固定翻译版本。请注意文件键名前面的下划线：它对应 `initialize_gt` 和 `I18nManager` 的 `version_id` 参数，并由 [`get_version_id`](/docs/python/reference/functions/get-version-id) 返回。

## `runtimeUrl` [#runtime-url]

**类型** `string` · **可选**

Runtime API 的基础 URL。配置加载器会将此键解析为 `runtime_url`，但当前的 `gt-flask` 和 `gt-fastapi` 集成不会将其传递给管理器，因此它在 Runtime 时不会生效。

*注意：`runtimeUrl` 会被读取，但框架集成不会使用它。*