Localization Module Technical Specifications

Every translation Aeion generates is cached so the same source text is never sent to an AI model twice for the same target language.

How a single translation request is resolved:

1. Fingerprint the source text. The source string is reduced to a stable cache key so lookups are exact-match and fast, regardless of table size.
2. Check the cache. If a cached translation exists for that text + target locale and it hasn't been marked "rejected," it's returned immediately — no AI call, and the entry's reuse count is incremented for your usage dashboard.
3. Load glossary rules. If nothing is cached, your tenant's glossary (brand terms, locale-specific phrasing, contextual guidance) is loaded and prepared for the AI prompt.
4. Translate. The AI provider configured for your tenant generates the translation with glossary rules applied.
5. Cache the result. The new translation is stored so every future request for that exact text + locale is served from cache.

Why exact-match caching instead of comparing raw text:

• Comparing raw strings gets slow as a translation history grows into the tens of thousands of entries.
• Text comparison also risks accidental partial matches or subtle formatting/whitespace differences producing cache misses that shouldn't happen.
• A stable, normalized cache key sidesteps both problems and keeps lookups fast at any scale.

Fuzzy/similarity matching (reusing a _close_ translation, not just an exact one) is on the roadmap; today the cache is exact-match only, which keeps translations predictable and auditable.

Translation jobs run on a background queue so saving content never blocks on AI calls. Two job types:

• Autonomous jobs — triggered automatically when a document is saved with missing translations.
• Batch jobs — triggered by bulk imports or manual "translate all" actions.

Duplicate-prevention:

• Autonomous jobs are deduplicated within a short time window — if the same content is saved multiple times in quick succession, only one translation job runs instead of one per save.
• Batch jobs are deduplicated by content — resubmitting an identical batch doesn't queue duplicate work.

Reliability: failed jobs retry automatically with increasing backoff between attempts, and both completed and failed jobs stay visible in the admin queue view for troubleshooting.

Why parallel workers instead of one-at-a-time: most AI providers rate-limit requests per minute, and most tenants save content in small bursts rather than constant firehose volume — so a handful of workers running in parallel comfortably keeps pace with normal usage while leaving headroom for bursts (bulk imports, catalog launches). High-volume tenants can add dedicated workers so they aren't sharing capacity.

Aeion doesn't poll for changes on a schedule — it reacts the moment content changes.

What triggers a translation check:

• A new document is created with localized fields.
• An existing document is saved (create and update share the same check).

What the automation does:

1. Checks whether the collection being saved has any fields marked localized: true.
2. Loads your tenant's active languages and default language.
3. For each localized field, checks which target languages don't yet have a translated value on that document.
4. Queues a translation job per missing language — fire-and-forget, so the save itself isn't slowed down.

What this looks like from the outside: save a page with an English title → a few seconds later, the Spanish, French, and German fields fill in automatically. No manual export, no waiting on a translator, no separate translation tool to log into.

Language settings: each tenant configures its own list of active languages and a default (source) language from the Localization Console.

Glossary: each tenant maintains its own glossary of brand terms with three rule types:

• do_not_translate — the term is always kept exactly as written.
• always_translate_as — the term maps to a specific translation per language.
• guidance — free-text instructions the AI follows when the term appears in context (e.g., "use the formal register for this word in German").

Translation review status: every translation carries a status of ai_generated, human_approved, or rejected. Marking an entry human_approved locks it in permanently; marking it rejected forces a fresh AI translation the next time that text is saved.