Production and deployment
In production, Citry does not read the .ftl files of a catalog package. It loads checked files that you generate before the build. Startup does less work, and the deployed application runs exactly the catalog that passed your checks.
This page covers compiling and packaging catalogs, testing the installed packages, and keeping caches and browser translations correct.
Citry() runs in production mode by default. With Citry(mode="development"), Citry reads the .ftl files directly, so you can edit translations without compiling.
Compile the catalogs
From a development checkout, run:
citry --app myproject.engine:app \
ext run i18n compile my_app_i18n
The command writes three files:
my_app_i18n/_compiled/
├── manifest.json
├── server.json
└── link.json
server.jsonholds the checked messages.link.jsonholds what Citry needs to combine the package with the application's locales, other packages, and fallbacks.manifest.jsonnames the package and records a hash of every source and generated file.
The package must be a writable folder in your source tree. Compile before you build a wheel or zip archive.
Ship compiled files
Every installed catalog package needs:
citry-i18n.toml
_compiled/manifest.json
_compiled/server.json
_compiled/link.json
Also include formats.json if the package has one. Include locales/**/*.ftl when the installed package should also load in development mode or be translated further. A production-only wheel may leave the .ftl files out.
For setuptools, use the package-data example in Organize catalogs. With another build backend, include the same paths.
Keep the package's __init__.py free of setup code. Citry finds the files by the package name you list in catalogs and needs no registration code.
Test the install
Test the built artifacts, not only your source checkout: the source distribution, the wheel rebuilt from it, and the installed wheel. From outside the repository, start a Citry instance in production mode and translate a message from the package. Check that the built archive contains every file listed in _compiled/manifest.json.
A catalog package also loads when installed as an importable zip archive.
Pass startup checks
When a production engine loads a catalog package, it checks:
- the fields and schema version in
citry-i18n.toml; - the package owner and source locale;
- the shape of the manifest;
- the hash of every generated file;
- the package and locale records in
link.json; and - that the files match what the current Citry compiler produces.
A missing file, an edited generated file, a broken record, a different owner, or files from an older compile stop startup. Citry never falls back to reading the .ftl files in production. Compile again and rebuild.
This applies to catalog packages only. Messages in your application's own components are loaded with the components, as in development.
Cache safely
A cached render must not be reused for another language. When a cached component's output depends on i18n, add the locale context's identity to the cache key through vary():
class LocalizedPrice(Component):
class Cache:
enabled = True
ttl = 300
def vary(self, kwargs, slots):
return {
"product": kwargs["product"].id,
"locale": self.component.i18n.context.identity,
}
The identity covers everything that can change the output: locale, fallback languages, direction, time zone, time-zone data version, catalog version, and format version.
Leaving the identity out means you promise the output is the same in every language.
Recreate after reload
A locale context records the catalog version it was built from. If a hot reload or another change loads a new catalog, operations on an older context raise an error that asks you to create a new one. This way one response never mixes text from two catalog versions.
Create each request's context after the application has loaded its catalog:
from citry.ext.i18n import make_context
context = make_context(app, locale=request.locale)
Send fewer messages
A page without a client provider (a <c-i18n client> element) sends no i18n code or messages to the browser.
With a client provider, the page includes only the messages its browser code uses, as found in literal $i18n calls, $c-tr bindings, and component.$i18n or this.$i18n calls, plus the messages they include and the format profiles they need. Citry never sends the whole catalog.
How more messages arrive depends on the setup:
- With Citry mounted in a web framework integration, the first response includes what the current locale needs.
switchLocale()andensureMessages()ask the server for more. The server rejects the whole request if it names an unknown or private message, an old catalog version, an unsupported locale, or too many messages. - For static output with no Citry server, the page includes the needed messages for every selectable locale. List message IDs built at runtime in
Component.I18n.client_messages.
Content that an Events handler renders again brings the messages it uses. An HTML fragment needs its own client provider.
Production checklist
Before you deploy:
- run
citry --app ... check; for locales that must be fully translated, also setrule_i18n_cross_language_fallback="error"or run the coverage check; - compile and verify every catalog package;
- include the descriptor and compiled files in each wheel, plus the
.ftlfiles if the wheel should also work in development mode; - test the installed packages in production mode;
- create a locale context for each request from its locale and time zone;
- add
context.identityto the key of every cache whose output is translated; - test client providers in every browser you support; and
- check
lang,dir, accessible names, and fallback text in at least one right-to-left locale.