# General Translation Python SDKs: Configuration
URL: https://generaltranslation.com/en-GB/docs/python/reference/config.mdx
---

title: Configuration
description: Configure the General Translation Python SDK through the gt.config.json file. API reference for gt.config.json.

---

`gt.config.json` contains the shared settings for a General Translation Python project. [`initialize_gt`](/docs/python/reference/functions/initialize-gt) reads it on startup (or you can pass its values to an [`I18nManager`](/docs/python/reference/classes/i18n-manager)), and any keyword arguments you pass override the file. This page documents every key the SDK reads.

*Note: The Python SDK is experimental.*

## Overview [#overview]

Place `gt.config.json` in your project root (the current working directory by default; override with `initialize_gt(..., config_path=...)`). Keys use **camelCase** in the file. All keys are optional; unknown keys are ignored. If the default file is absent, an empty config is used — but an explicit `config_path` that does not exist raises `FileNotFoundError`, and invalid JSON raises `ValueError`.

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

| Key                                | Description                                  | Type       | Optional | Default |
| ---------------------------------- | -------------------------------------------- | ---------- | -------- | ------- |
| [`projectId`](#project-id)         | Project ID; enables the CDN loader when set. | `string`   | Yes      | —       |
| [`defaultLocale`](#default-locale) | Source and fallback locale.                  | `string`   | Yes      | `"en"`  |
| [`locales`](#locales)              | Supported target locale codes.               | `string[]` | Yes      | —       |
| [`cacheUrl`](#cache-url)           | CDN base URL used to load translations.      | `string`   | Yes      | —       |
| [`customMapping`](#custom-mapping) | Custom locale codes and property overrides.  | `object`   | Yes      | —       |
| [`_versionId`](#version-id)        | Pinned translation version.                  | `string`   | Yes      | —       |
| [`runtimeUrl`](#runtime-url)       | Runtime API base URL.                        | `string`   | Yes      | —       |

## `projectId` [#project-id]

**Type** `string` · **Optional**

Your General Translation Project ID. When set (and no `load_translations` callback is provided), the SDK loads translations from the CDN at `{cacheUrl}/{projectId}/{locale}`. This maps to the `project_id` argument of `initialize_gt` and `I18nManager`.

## `defaultLocale` [#default-locale]

**Type** `string` · **Optional** · **Default** `"en"`

The source locale your content is written in, and the fallback locale when no translation is found. If it is not set in either the config or the `initialize_gt` call, it falls back to the library default `"en"` (the `LIBRARY_DEFAULT_LOCALE` constant).

## `locales` [#locales]

**Type** `string[]` · **Optional**

The target locales to support. The default locale is always included in the manager's locale set, even if omitted here. Eager loading fetches translations for these locales at startup.

## `cacheUrl` [#cache-url]

**Type** `string` · **Optional**

The CDN base URL used to build translation requests (`{cacheUrl}/{projectId}/{locale}`). The General Translation CDN is `https://cdn.gtx.dev`.

*Note: When `cacheUrl` is not set, the manager currently passes an empty base URL to the remote loader rather than applying the CDN default — set `cacheUrl` explicitly for CDN loading.*

## `customMapping` [#custom-mapping]

**Type** `object` · **Optional**

A mapping of custom locale codes to standard codes or to property overrides (for example, `{ "en-US": { "name": "English", "nativeName": "English" } }`). Maps to the `custom_mapping` argument and the [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) type in `generaltranslation`.

## `_versionId` [#version-id]

**Type** `string` · **Optional**

A pinned translation version to load. Note the leading underscore in the file key; it maps to the `version_id` argument of `initialize_gt` and `I18nManager`, and is returned by [`get_version_id`](/docs/python/reference/functions/get-version-id).

## `runtimeUrl` [#runtime-url]

**Type** `string` · **Optional**

The runtime API base URL. The config loader parses this key into `runtime_url`, but the current `gt-flask` and `gt-fastapi` integrations do not pass it to the manager, so it has no effect at runtime.

*Note: `runtimeUrl` is read but unused by the framework integrations.*