From 58597cdf2a0d201b36c066e4862836fcc77b2e30 Mon Sep 17 00:00:00 2001
From: moss-bryophyta <261561981+moss-bryophyta@users.noreply.github.com>
Date: Wed, 18 Mar 2026 17:06:41 -0700
Subject: [PATCH 1/4] feat: add get_version_id() across gt-i18n, gt-fastapi,
 gt-flask

Mirrors the useVersionId/getVersionId hook added to the JS packages
in generaltranslation/gt#1121.

- I18nManager: new version_id param + get_version_id() method
- Config loader: reads _versionId from gt.config.json
- Helper: get_version_id() convenience function
- Re-exported from gt-i18n, gt-fastapi, gt-flask
---
 packages/gt-fastapi/src/gt_fastapi/__init__.py             | 3 ++-
 packages/gt-fastapi/src/gt_fastapi/_setup.py               | 3 +++
 packages/gt-flask/src/gt_flask/__init__.py                 | 3 ++-
 packages/gt-flask/src/gt_flask/_setup.py                   | 3 +++
 packages/gt-i18n/src/gt_i18n/__init__.py                   | 3 +++
 packages/gt-i18n/src/gt_i18n/helpers/_version_id.py        | 7 +++++++
 packages/gt-i18n/src/gt_i18n/i18n_manager/_i18n_manager.py | 6 ++++++
 packages/gt-i18n/src/gt_i18n/internal/_load_gt_config.py   | 2 ++
 8 files changed, 28 insertions(+), 2 deletions(-)
 create mode 100644 packages/gt-i18n/src/gt_i18n/helpers/_version_id.py

diff --git a/packages/gt-fastapi/src/gt_fastapi/__init__.py b/packages/gt-fastapi/src/gt_fastapi/__init__.py
index 9622b56..097e34b 100644
--- a/packages/gt-fastapi/src/gt_fastapi/__init__.py
+++ b/packages/gt-fastapi/src/gt_fastapi/__init__.py
@@ -1,6 +1,6 @@
 """FastAPI integration for General Translation."""
 
-from gt_i18n import declare_static, declare_var, decode_vars, derive, get_default_locale, get_locale, get_locales, t
+from gt_i18n import declare_static, declare_var, decode_vars, derive, get_default_locale, get_locale, get_locales, get_version_id, t
 
 from gt_fastapi._setup import initialize_gt
 
@@ -14,4 +14,5 @@
     "get_locale",
     "get_locales",
     "get_default_locale",
+    "get_version_id",
 ]
diff --git a/packages/gt-fastapi/src/gt_fastapi/_setup.py b/packages/gt-fastapi/src/gt_fastapi/_setup.py
index c33e121..7a84fd6 100644
--- a/packages/gt-fastapi/src/gt_fastapi/_setup.py
+++ b/packages/gt-fastapi/src/gt_fastapi/_setup.py
@@ -56,6 +56,8 @@ def initialize_gt(
     resolved_cache_url = cache_url or file_config.get("cache_url")
     resolved_custom_mapping = custom_mapping or file_config.get("custom_mapping")
 
+    resolved_version_id = file_config.get("version_id")
+
     manager = I18nManager(
         default_locale=resolved_default_locale,
         locales=resolved_locales,
@@ -63,6 +65,7 @@ def initialize_gt(
         project_id=resolved_project_id,
         cache_url=resolved_cache_url,
         load_translations=load_translations,
+        version_id=resolved_version_id,
     )
     set_i18n_manager(manager)
 
diff --git a/packages/gt-flask/src/gt_flask/__init__.py b/packages/gt-flask/src/gt_flask/__init__.py
index 73334f5..c87858f 100644
--- a/packages/gt-flask/src/gt_flask/__init__.py
+++ b/packages/gt-flask/src/gt_flask/__init__.py
@@ -1,6 +1,6 @@
 """Flask integration for General Translation."""
 
-from gt_i18n import declare_static, declare_var, decode_vars, derive, get_default_locale, get_locale, get_locales, t
+from gt_i18n import declare_static, declare_var, decode_vars, derive, get_default_locale, get_locale, get_locales, get_version_id, t
 
 from gt_flask._setup import initialize_gt
 
@@ -14,4 +14,5 @@
     "get_locale",
     "get_locales",
     "get_default_locale",
+    "get_version_id",
 ]
diff --git a/packages/gt-flask/src/gt_flask/_setup.py b/packages/gt-flask/src/gt_flask/_setup.py
index 4ecb254..4bfec92 100644
--- a/packages/gt-flask/src/gt_flask/_setup.py
+++ b/packages/gt-flask/src/gt_flask/_setup.py
@@ -56,6 +56,8 @@ def initialize_gt(
     resolved_cache_url = cache_url or file_config.get("cache_url")
     resolved_custom_mapping = custom_mapping or file_config.get("custom_mapping")
 
+    resolved_version_id = file_config.get("version_id")
+
     manager = I18nManager(
         default_locale=resolved_default_locale,
         locales=resolved_locales,
@@ -63,6 +65,7 @@ def initialize_gt(
         project_id=resolved_project_id,
         cache_url=resolved_cache_url,
         load_translations=load_translations,
+        version_id=resolved_version_id,
     )
     set_i18n_manager(manager)
 
diff --git a/packages/gt-i18n/src/gt_i18n/__init__.py b/packages/gt-i18n/src/gt_i18n/__init__.py
index 7c24ada..de617ce 100644
--- a/packages/gt-i18n/src/gt_i18n/__init__.py
+++ b/packages/gt-i18n/src/gt_i18n/__init__.py
@@ -7,6 +7,7 @@
     get_locale,
     get_locales,
 )
+from gt_i18n.helpers._version_id import get_version_id
 from gt_i18n.i18n_manager import (
     ContextVarStorageAdapter,
     I18nManager,
@@ -49,6 +50,8 @@
     "get_locale",
     "get_locales",
     "get_default_locale",
+    # Version
+    "get_version_id",
     # Derive / variable helpers
     "declare_var",
     "derive",
diff --git a/packages/gt-i18n/src/gt_i18n/helpers/_version_id.py b/packages/gt-i18n/src/gt_i18n/helpers/_version_id.py
new file mode 100644
index 0000000..4a50eee
--- /dev/null
+++ b/packages/gt-i18n/src/gt_i18n/helpers/_version_id.py
@@ -0,0 +1,7 @@
+from gt_i18n.i18n_manager._singleton import get_i18n_manager
+
+
+def get_version_id() -> str | None:
+    """Get the version ID for the current source, if set."""
+    manager = get_i18n_manager()
+    return manager.get_version_id()
diff --git a/packages/gt-i18n/src/gt_i18n/i18n_manager/_i18n_manager.py b/packages/gt-i18n/src/gt_i18n/i18n_manager/_i18n_manager.py
index 2004f52..ea6a001 100644
--- a/packages/gt-i18n/src/gt_i18n/i18n_manager/_i18n_manager.py
+++ b/packages/gt-i18n/src/gt_i18n/i18n_manager/_i18n_manager.py
@@ -43,7 +43,9 @@ def __init__(
         store_adapter: StorageAdapter | None = None,
         load_translations: TranslationsLoader | None = None,
         cache_expiry_time: int = 60_000,
+        version_id: str | None = None,
     ) -> None:
+        self._version_id = version_id
         self._default_locale = default_locale
         locales_set: set[str] = {default_locale, *(locales or [])}
         self._locales = list(locales_set)
@@ -82,6 +84,10 @@ def get_gt_instance(self) -> GT:
             custom_mapping=self._custom_mapping,
         )
 
+    def get_version_id(self) -> str | None:
+        """Get the version ID for the current source, if set."""
+        return self._version_id
+
     def get_locales(self) -> list[str]:
         return list(self._locales)
 
diff --git a/packages/gt-i18n/src/gt_i18n/internal/_load_gt_config.py b/packages/gt-i18n/src/gt_i18n/internal/_load_gt_config.py
index 7dac98d..4c088df 100644
--- a/packages/gt-i18n/src/gt_i18n/internal/_load_gt_config.py
+++ b/packages/gt-i18n/src/gt_i18n/internal/_load_gt_config.py
@@ -16,6 +16,7 @@
     "cacheUrl": "cache_url",
     "runtimeUrl": "runtime_url",
     "customMapping": "custom_mapping",
+    "_versionId": "version_id",
 }
 
 
@@ -26,6 +27,7 @@ class GTConfig(TypedDict, total=False):
     cache_url: str
     runtime_url: str
     custom_mapping: CustomMapping
+    version_id: str
 
 
 def load_gt_config(config_path: str | None = None) -> GTConfig:

From 50f5424f7e6934b057892ac8173ddb9db244969d Mon Sep 17 00:00:00 2001
From: moss-bryophyta <261561981+moss-bryophyta@users.noreply.github.com>
Date: Wed, 18 Mar 2026 19:35:19 -0700
Subject: [PATCH 2/4] fix: add version_id parameter to initialize_gt() in
 gt-fastapi and gt-flask
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Greptile correctly identified that version_id was the only config value
not passable as a direct parameter. Now follows the same pattern as
project_id, cache_url, etc. — function argument takes precedence over
file config fallback.

Also adds changeset for the release.
---
 .sampo/changesets/fix-version-id-param.md    | 6 ++++++
 packages/gt-fastapi/src/gt_fastapi/_setup.py | 4 +++-
 packages/gt-flask/src/gt_flask/_setup.py     | 4 +++-
 3 files changed, 12 insertions(+), 2 deletions(-)
 create mode 100644 .sampo/changesets/fix-version-id-param.md

diff --git a/.sampo/changesets/fix-version-id-param.md b/.sampo/changesets/fix-version-id-param.md
new file mode 100644
index 0000000..0bb7aa8
--- /dev/null
+++ b/.sampo/changesets/fix-version-id-param.md
@@ -0,0 +1,6 @@
+---
+pypi/gt-fastapi: patch
+pypi/gt-flask: patch
+---
+
+fix: allow `version_id` to be passed as a direct parameter to `initialize_gt()`
diff --git a/packages/gt-fastapi/src/gt_fastapi/_setup.py b/packages/gt-fastapi/src/gt_fastapi/_setup.py
index 7a84fd6..a95b5a1 100644
--- a/packages/gt-fastapi/src/gt_fastapi/_setup.py
+++ b/packages/gt-fastapi/src/gt_fastapi/_setup.py
@@ -20,6 +20,7 @@ def initialize_gt(
     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,
@@ -34,6 +35,7 @@ def initialize_gt(
         locales: Target locales.
         project_id: GT project ID for CDN loading.
         cache_url: CDN base URL override.
+        version_id: Version ID for pinning translations.
         get_locale: Custom locale detection callback ``(request) -> str``.
         load_translations: Custom translation loader ``(locale) -> dict``.
         eager_loading: Load all translations at startup (default True).
@@ -56,7 +58,7 @@ def initialize_gt(
     resolved_cache_url = cache_url or file_config.get("cache_url")
     resolved_custom_mapping = custom_mapping or file_config.get("custom_mapping")
 
-    resolved_version_id = file_config.get("version_id")
+    resolved_version_id = version_id or file_config.get("version_id")
 
     manager = I18nManager(
         default_locale=resolved_default_locale,
diff --git a/packages/gt-flask/src/gt_flask/_setup.py b/packages/gt-flask/src/gt_flask/_setup.py
index 4bfec92..004ee73 100644
--- a/packages/gt-flask/src/gt_flask/_setup.py
+++ b/packages/gt-flask/src/gt_flask/_setup.py
@@ -20,6 +20,7 @@ def initialize_gt(
     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,
@@ -34,6 +35,7 @@ def initialize_gt(
         locales: Target locales.
         project_id: GT project ID for CDN loading.
         cache_url: CDN base URL override.
+        version_id: Version ID for pinning translations.
         get_locale: Custom locale detection callback ``(request) -> str``.
         load_translations: Custom translation loader ``(locale) -> dict``.
         eager_loading: Load all translations at startup (default True).
@@ -56,7 +58,7 @@ def initialize_gt(
     resolved_cache_url = cache_url or file_config.get("cache_url")
     resolved_custom_mapping = custom_mapping or file_config.get("custom_mapping")
 
-    resolved_version_id = file_config.get("version_id")
+    resolved_version_id = version_id or file_config.get("version_id")
 
     manager = I18nManager(
         default_locale=resolved_default_locale,

From be89c6a5e952e97a1f8b0af01fdfd46c02a957cc Mon Sep 17 00:00:00 2001
From: moss-bryophyta <261561981+moss-bryophyta@users.noreply.github.com>
Date: Wed, 18 Mar 2026 19:36:28 -0700
Subject: [PATCH 3/4] fix: resolve lint errors in gt-fastapi and gt-flask
 __init__.py

---
 packages/gt-fastapi/src/gt_fastapi/__init__.py | 12 +++++++++++-
 packages/gt-flask/src/gt_flask/__init__.py     | 12 +++++++++++-
 2 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/packages/gt-fastapi/src/gt_fastapi/__init__.py b/packages/gt-fastapi/src/gt_fastapi/__init__.py
index 097e34b..ad6a4c1 100644
--- a/packages/gt-fastapi/src/gt_fastapi/__init__.py
+++ b/packages/gt-fastapi/src/gt_fastapi/__init__.py
@@ -1,6 +1,16 @@
 """FastAPI integration for General Translation."""
 
-from gt_i18n import declare_static, declare_var, decode_vars, derive, get_default_locale, get_locale, get_locales, get_version_id, t
+from gt_i18n import (
+    declare_static,
+    declare_var,
+    decode_vars,
+    derive,
+    get_default_locale,
+    get_locale,
+    get_locales,
+    get_version_id,
+    t,
+)
 
 from gt_fastapi._setup import initialize_gt
 
diff --git a/packages/gt-flask/src/gt_flask/__init__.py b/packages/gt-flask/src/gt_flask/__init__.py
index c87858f..f4d9202 100644
--- a/packages/gt-flask/src/gt_flask/__init__.py
+++ b/packages/gt-flask/src/gt_flask/__init__.py
@@ -1,6 +1,16 @@
 """Flask integration for General Translation."""
 
-from gt_i18n import declare_static, declare_var, decode_vars, derive, get_default_locale, get_locale, get_locales, get_version_id, t
+from gt_i18n import (
+    declare_static,
+    declare_var,
+    decode_vars,
+    derive,
+    get_default_locale,
+    get_locale,
+    get_locales,
+    get_version_id,
+    t,
+)
 
 from gt_flask._setup import initialize_gt
 

From 23819b52aee9b00ca66671445e7a82d12d5e9028 Mon Sep 17 00:00:00 2001
From: moss-bryophyta <261561981+moss-bryophyta@users.noreply.github.com>
Date: Wed, 18 Mar 2026 19:37:32 -0700
Subject: [PATCH 4/4] chore: include gt-i18n in changeset

---
 .sampo/changesets/fix-version-id-param.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.sampo/changesets/fix-version-id-param.md b/.sampo/changesets/fix-version-id-param.md
index 0bb7aa8..c4f6fd0 100644
--- a/.sampo/changesets/fix-version-id-param.md
+++ b/.sampo/changesets/fix-version-id-param.md
@@ -1,4 +1,5 @@
 ---
+pypi/gt-i18n: patch
 pypi/gt-fastapi: patch
 pypi/gt-flask: patch
 ---