Table of Contents
How AI Context and Glossary Management Keep Your Brand Consistent Across Languages
Your product's terminology is part of your brand. When a user sees "workspace" in English, "espacio de trabajo" in one Spanish screen and "área de trabajo" in another, the inconsistency chips away at trust. Multiply that across 15 languages and hundreds of terms, and you have a brand coherence problem that no amount of manual review can solve.
This tutorial walks through better-i18n's AI context and glossary management features — from automated website analysis to term approval workflows to DeepL sync — so you can enforce brand terminology consistency at scale.
What You Will Build
By the end of this tutorial, you will have:
- A context profile built from your website's actual content
- A glossary of brand terms extracted automatically and refined by your team
- An approval workflow that prevents unapproved terms from reaching production
- A DeepL sync that enforces your glossary in machine translations
Step 1: Analyze Your Website With the Context Crawler
The fastest way to bootstrap your translation glossary is to let AI analyze what you have already published.
Run a Website Analysis
In your better-i18n project dashboard, navigate to AI Context and select Website Analysis. Enter your product's marketing site URL — for example, https://yourproduct.com.
The Context Crawler uses the Firecrawl API to render and extract content from your pages. Unlike simple HTML scrapers, Firecrawl handles JavaScript-rendered content, single-page applications, and dynamically loaded sections. It follows internal links to build a comprehensive map of your site's content.
What the Analysis Produces
After crawling, the AI analyzes the extracted content and identifies:
- Brand terms — Product names, feature names, and coined vocabulary (e.g., "Workstream," "Sprint Board," "FlowMetrics")
- Navigation vocabulary — Menu labels, CTAs, and breadcrumb text that users encounter repeatedly
- Domain-specific language — Industry terms your product uses that need precise, consistent translations
- Tone signals — Whether your content is formal, casual, or technical, helping the AI translate with the right register
Each detected term includes the source URLs where it was found, a suggested definition, and frequency data showing how often it appears across your site.
Step 2: Analyze Your Repository for Framework Context
Website analysis captures your public-facing terminology. Repository analysis captures the technical context that makes AI translations more accurate.
Connect Your GitHub Repository
In the AI Context section, select Repository Analysis and provide your GitHub repository URL. The analyzer supports public repos directly and private repos through your GitHub integration.
What Repository Analysis Detects
The analyzer examines your codebase to identify:
- Framework and i18n library — React with next-intl? Vue with vue-i18n? Flutter with ARB files? The detected stack tells the AI which interpolation syntax, pluralization format, and message conventions to use.
- Namespace structure — How your project organizes translation keys, so new translations follow existing patterns.
- Existing terminology — Terms already used in your codebase that should be in the glossary but might not be.
- String patterns — Date formats, number formats, and pluralization approaches that inform translation rules.
This context is attached to your project and used automatically in every AI translation job — no manual prompt engineering required.
Step 3: Review and Approve Glossary Terms
Both analysis modes produce candidate terms that enter your glossary as drafts. This is where the term workflow becomes critical.
The Term Lifecycle
Every glossary term follows a four-stage lifecycle:
| Status | Meaning | Enforced in Translation? |
|---|---|---|
| Draft | Newly created or imported. Visible but not enforced. | No |
| Submitted | Ready for review. Signals completeness. | No |
| Approved | Reviewed and accepted. Active in all workflows. | Yes |
| Rejected | Not accepted. Can be revised and resubmitted. | No |
Only approved terms are injected into AI translation prompts and highlighted in the review editor. This prevents the common glossary management problem where half-finished or contested terms cause more inconsistency than they solve.
Reviewing Proposed Terms
After a website or repository analysis, navigate to your glossary and filter by Draft status. For each proposed term:
- Verify the source term — Is this actually a brand term that needs controlled translation, or is it generic language?
- Add or edit translations — The crawler may propose translations based on detected patterns. Review and correct them for each target language.
- Set rules — Mark terms as never-translate if they should pass through unchanged (product names, brand names, technical identifiers).
- Submit for approval — Once you are satisfied with the term definition and translations, submit it for team review.
- Approve or reject — A reviewer (you or a team member) approves the term for enforcement or rejects it with feedback.
Practical Example
Suppose your website analysis finds that "FlowMetrics" appears 47 times across your site. The crawler proposes it as a brand term with a never-translate flag. You review it, confirm the flag is correct, add a definition ("Our proprietary analytics dashboard"), and approve it. From this moment:
- AI translation will never translate "FlowMetrics" in any language
- Human reviewers will see it highlighted if they accidentally translate it
- DeepL (after sync) will preserve it unchanged
Step 4: Bulk Import Existing Terms
If you are migrating from another localization tool or have a spreadsheet of approved terminology, you do not need to enter terms one by one.
JSON Import
Prepare a JSON file with your terms structured as an array of objects. Each object includes the source term, target translations per language, and optional metadata (definition, part of speech, domain tag, never-translate flag).
Upload the file through the glossary's Import function. The importer:
- Validates entries against your project's configured languages
- Deduplicates against existing glossary terms
- Reports conflicts before applying changes
- Creates all imported terms with draft status
After import, run through the approval workflow to activate the terms.
JSON Export
You can export your glossary at any time as structured JSON — useful for backup, migration, feeding terminology into external documentation pipelines, or sharing with translation agencies who work outside better-i18n.
Step 5: Sync Your Glossary to DeepL
If your translation pipeline includes DeepL — whether through better-i18n's AI translation or direct DeepL API calls — glossary sync ensures your terminology rules are enforced at the provider level.
How the Sync Works
- Navigate to your glossary settings and select Sync to Provider.
- better-i18n converts your approved terms into DeepL's glossary format, automatically mapping your multi-language glossary into the language-pair structure DeepL requires.
- The glossary is uploaded to DeepL via their API.
- All subsequent DeepL translations for your configured language pairs will respect your terminology.
When to Re-Sync
Re-sync after any batch of glossary changes — new approved terms, updated translations, or removed entries. The sync is idempotent: it replaces the previous DeepL glossary with the current state of your approved terms.
Step 6: Verify Enforcement in Practice
With your glossary approved and synced, run a test translation to see enforcement in action.
AI Translation Test
Create a test string that includes several glossary terms. Run AI translation and inspect the output:
- Approved terms should appear exactly as defined in your glossary
- Never-translate terms should pass through unchanged
- The consistency validator should show zero glossary violations
Review Editor Test
Open the review editor for a translation that contains glossary terms:
- Glossary terms should be highlighted inline
- Typing an unapproved variant should trigger an autocomplete suggestion with the approved translation
- Incorrectly used terms should be underlined with a tooltip explaining the approved term
Maintaining Your Glossary Over Time
A glossary is not a set-and-forget tool. Your product evolves, and your terminology evolves with it.
Periodic Re-Crawling
Run website analysis quarterly (or after major product launches) to detect new terminology. New terms enter as drafts, keeping your glossary current without disrupting existing enforcement.
Repository Re-Analysis
When you adopt a new framework, add a new i18n library, or restructure your namespace hierarchy, run repository analysis again to update your project's context profile.
Term Retirement
When a product feature is renamed or retired, update or delete the corresponding glossary term. The term workflow ensures that changes go through review before affecting translations.
Export for Auditing
Periodically export your glossary as JSON for compliance auditing, translation agency onboarding, or backup. The export includes all term metadata, translations, and status information.
Key Takeaways
- Start with analysis, not manual entry. The Context Crawler's website and repository analysis can bootstrap a glossary in hours instead of weeks.
- Use the approval workflow. Draft-to-approved lifecycle prevents glossary pollution and ensures only vetted terms are enforced.
- Sync to DeepL for provider-level enforcement. Your terminology rules should travel with the translation engine, not just the translation tool.
- Maintain continuously. Periodic re-crawling and re-analysis keep your glossary aligned with your evolving product.
Translation glossary management is not about creating a reference document that translators might consult. It is about building an active enforcement system that makes brand terminology consistency automatic across every language, every translator, and every translation engine your product uses.
Get started with better-i18n and build your first AI-powered glossary today — or explore the Glossary Management and Context Crawler feature pages for deeper technical details.
