docs(python): match the quickstart to the fixed SDK

[Kevin-Liu-01]

Summary

The Python quickstart could not reach a translated response, and the reference pages described two SDK bugs as behavior:

• In gt-i18n 0.1.0 to 0.3.0, translations expire after 60 s and t() falls back to the source text.
• gt-flask eager-loads only the locales argument, so the quickstart's app, which lists its locales in gt.config.json, never loads translations.
• Without cacheUrl, the CDN loader gets an empty base URL.
• The quickstart ran npx gt translate without --publish, so the CDN never had translations for the app to load.

gt-python 0.3.1 fixes the SDK bugs (generaltranslation/gt-python generaltranslation/gt-python#36 (k/gt-i18n-cache-expiry) and generaltranslation/gt-python#37 (k/flask-fastapi-configured-locales)). These pages now describe that release:

• python/quickstart.mdx: installs gt-flask>=0.3.1 or gt-fastapi>=0.3.1, says that initialize_gt loads the configured locales and reloads them in the background after 60 s, runs npx gt translate --publish with a note to enable the CDN first, and adds a step 6 that requests the app with Accept-Language: es. That step notes that Flask escapes non-ASCII characters in JSON and that Uvicorn serves on port 8000.
• python/guides/configuring.mdx: drops the two notes that described the bugs, describes the reload behavior and the empty-response rule, gives the CDN URL with the pinned version, and documents _branchId and "cacheUrl": null.
• python/reference/classes/i18n-manager.mdx: documents branch_id, the CDN default and the empty cache_url, the new get_translations_blocking and load_all_translations_blocking, and what get_translations and get_translations_sync return after expiry.
• python/reference/config.mdx: cacheUrl is string | null with the CDN as its default, the empty-base-URL note is gone, and _versionId and the new _branchId give the CDN URL they produce.
• python/reference/functions/initialize-gt.mdx: eager loading uses the resolved locales on both frameworks, each request loads its configured locale, and cache_url documents the default and how to turn CDN loading off.

Size: 5 files, +64/-28.

Decisions

• The quickstart pins >=0.3.1, because an older version still has the 60 s expiry, and a reader who already has 0.1.0 installed would otherwise keep it.
• The quickstart keeps CDN delivery and adds --publish. Local files remain documented in "Storing translations locally", which the step 5 note links.

Test plan

Run on this branch (k/python-quickstart-loads-translations at 6272fd4, on origin/main f93de7c), in scripts/ after npm ci:

• validate-links: all links valid
• validate:unsafe-html and validate:callouts: 546 MDX files each, clean
• validate:reference-links: 500 MDX files against 301 reference symbol aliases, clean
• validate:structure, validate:blog-order and validate:kb: clean
• test: 7 scripts, 155 cases passed
• typecheck: clean
• The CI check for javascript: URLs in MDX finds nothing.

Not run: the CI build-content job, which builds the whole content app.

Earlier, on the combined SDK fix: the quickstart's app, run exactly as these pages print it against a stand-in CDN, answered in Spanish.

Merge order

1. generaltranslation/gt-python: fix(release): publish every package version missing from PyPI (fix(release): publish every package version missing from PyPI gt-python#35 (k/publish-missing-versions)).
2. generaltranslation/gt-python: the gt-i18n PR, then the gt-flask and gt-fastapi PR stacked on it.
3. generaltranslation/gt-python: sampo's release PR, which publishes gt-i18n, gt-flask and gt-fastapi 0.3.1.
4. This PR, after 0.3.1 is on PyPI.

🤖 Generated with Claude Code

[cursor]

Risk: low. Approved. This is a small, docs-only update to the Python Quickstart and related reference pages, with no automated-review findings and an easy rollback.

  

_{Sent by Cursor Approval Agent: Pull Request Router}