feat: add get_version_id() across gt-i18n, gt-fastapi, gt-flask

.sampo/changesets/fix-version-id-param.md

@@ -0,0 +1,7 @@
+---
+pypi/gt-i18n: patch
+pypi/gt-fastapi: patch
+pypi/gt-flask: patch
+---
+
+fix: allow `version_id` to be passed as a direct parameter to `initialize_gt()`

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, 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 +24,5 @@
     "get_locale",
     "get_locales",
     "get_default_locale",
+    "get_version_id",
 ]

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,13 +58,16 @@ 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 = version_id or file_config.get("version_id")
+
     manager = I18nManager(
         default_locale=resolved_default_locale,
         locales=resolved_locales,
         custom_mapping=resolved_custom_mapping,
         project_id=resolved_project_id,
         cache_url=resolved_cache_url,
         load_translations=load_translations,
+        version_id=resolved_version_id,
     )
     set_i18n_manager(manager)
 

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, 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 +24,5 @@
     "get_locale",
     "get_locales",
     "get_default_locale",
+    "get_version_id",
 ]

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,13 +58,16 @@ 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 = version_id or file_config.get("version_id")
+
     manager = I18nManager(
         default_locale=resolved_default_locale,
         locales=resolved_locales,
         custom_mapping=resolved_custom_mapping,
         project_id=resolved_project_id,
         cache_url=resolved_cache_url,
         load_translations=load_translations,
+        version_id=resolved_version_id,
     )
     set_i18n_manager(manager)
 

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",

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()

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)
 

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: