Internationalization (i18n) Guide
This document covers internationalization implementation, translation workflows, and management tools for the Waldur HomePort project.
Developer Guide
Basic Translation Usage
Use the translate
function to mark strings for translation:
1 2 3 4 5 6 7 |
|
JSX Integration
Rendering JSX Elements Inside Translated Strings
Use formatJsxTemplate
for embedding React components:
1 2 3 4 5 6 |
|
Rendering Links and Markup
Use formatJsx
for translatable text with embedded links:
1 2 3 4 5 6 7 |
|
Translation Guidelines
β Do:
- Always mark complete sentences for translation
- Use descriptive variable names in templates
- Provide context when the same word has different meanings
- Use proper capitalization in source strings
β Don't:
- Combine string fragments at runtime
- Translate technical terms that are universally understood
- Use overly complex nested interpolations
- Ignore cultural adaptation needs
1 2 3 4 5 |
|
Translation Extraction
Extract translatable strings with rich context for better translations:
1 |
|
Features:
- Scans all
.ts
and.tsx
files insrc/
- Finds
translate()
function calls and extracts string literals - Updates
template.json
with rich context information - UI Element Detection: Identifies buttons, forms, titles, error messages
- Variable Analysis: Detects variable types (number, date, string, url)
- Text Characteristics: Analyzes sentence structure, markup, length
- Semantic Context: Captures React components and function names
- Translator Notes: Generates contextual guidance automatically
Example output:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
|
Translation Management Tools
Available Commands
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
Comprehensive Analysis
Analyze translation usage and quality issues:
1 2 3 4 5 6 7 8 |
|
Reports provided:
- Unused translations: Keys in
template.json
not found in code - Missing translations: Hardcoded strings that should use
translate()
- Locale coverage: Translation completeness for each language
- Deprecated translations: Translations in locale files but not used in code
- Empty translations: Locale entries that need content
- Context information: Where strings are used and in what context
Translation Cleanup
Remove deprecated translations from locale files:
1 2 |
|
What it does:
- Compares locale files against the current
template.json
(generated from code) - Removes translations that exist in locale files but are no longer used in the codebase
- Preserves all valid translations that are still referenced in the code
- Processes all locale files (*.json) in the
/locales/
directory
Safety features:
- Only removes translations that don't exist in the generated template
- Maintains proper JSON formatting and structure
- Shows detailed report of what was removed from each file
- Preserves all currently used translations
Example output:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
CI/CD Validation
Validate translation quality in build pipelines:
1 2 3 4 5 6 7 8 9 10 11 |
|
Command line options:
--max-unused N
: Maximum allowed unused translations (default: 50)--max-missing N
: Maximum allowed missing translations (default: 100)--fail-on-unused
: Fail CI if unused translations exceed limit--fail-on-missing
: Fail CI if missing translations exceed limit--warn-only
: Show warnings but don't fail CI
Enhanced Context Analysis
UI Element Detection
The enhanced extraction automatically detects UI context:
Button Types:
button
,submit_button
,action_button
,delete_button
cancel_button
,primary_button
Form Elements:
input_field
,select_field
,textarea
label
,field_label
,placeholder
Messages:
error_message
,success_message
,warning_message
notification_message
,tooltip
Navigation:
title
,page_title
,section_title
menu_item
,link
,navigation_link
Variable Type Analysis
Automatically infers variable types for better translation guidance:
Detected Types:
number
: count, total, amount, size, indexdate
: date, time, created, updated, expiresstring
: name, title, label, text, descriptionurl
: url, link, href, pathemail
: email, mail
Example with variables:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
Automatic Translator Notes
The system generates contextual guidance:
- UI Context: "This text appears on a button. Keep it short and action-oriented."
- Variable Handling: "Contains variables that may need reordering in your language."
- Markup Preservation: "Contains HTML/JSX markup. Preserve all tags and structure."
- Text Format: "Original text is in ALL CAPS. Consider if this emphasis is appropriate."
- Grammar: "This is a question. Ensure question format is appropriate in your language."
Translation Workflow
Local Translation Management
This project uses a local-first approach to translation management. All translations are managed directly in the repository without external translation services.
Key Benefits
- Direct Control: All translations are in the repository and version-controlled
- Enhanced Context: Translators have access to rich context information from enhanced extraction
- Quality Tools: Built-in analysis tools for translation quality and completeness
- No Dependencies: No reliance on external translation platforms or services
Development Workflow
- Development: Use
translate()
function in code - Extraction: Run
yarn i18n:extract
to updatetemplate.json
with rich context - Translation: Translators work directly with locale files in
/locales/
directory using enhanced context information - Validation: Run
yarn i18n:check
to verify quality and completeness - Review: Use context-aware analysis tools to improve translation quality
Translation Process
For New Strings
- Developer adds
translate('New string')
in code - Run
yarn i18n:extract
to add totemplate.json
with rich context - Translator adds translation to relevant locale files (e.g.,
/locales/nb.json
) - Use
yarn i18n:check:locales
to verify completeness
Quality Assurance
- Regular cleanup: Monthly
yarn i18n:clean
to remove deprecated translations from locale files - Coverage monitoring:
yarn i18n:check:locales
for translation completeness - Context validation: Rich context is provided by default in
template.json
- Cultural review: Native speaker validation of context-aware translations
- Direct locale editing: Translators work directly with locale files in
/locales/
directory
Before cleanup workflow:
- Run
yarn i18n:extract
to updatetemplate.json
with current code translations - Run
yarn i18n:clean
to remove deprecated translations from locale files - Run
yarn i18n:check
to verify the cleanup was successful
Continuous Integration
The local translation management approach integrates seamlessly with CI/CD:
Add to .gitlab-ci.yml
:
1 2 3 4 5 6 7 8 |
|
Best Practices
For Developers
- Complete Sentences: Always translate complete, meaningful units
1 2 3 4 5 |
|
- Meaningful Context: Provide context for translators
1 2 3 4 5 6 |
|
- Variable Naming: Use descriptive variable names
1 2 3 4 5 |
|
For Translators
- Use Enhanced Context: Leverage UI type information and translator notes
- Preserve Markup: Keep all HTML/JSX tags intact
- Consider Variables: Pay attention to variable types and positioning
- Cultural Adaptation: Adapt tone and formality to target culture
- Consistency: Use established terminology from context analysis
For Maintainers
- Regular Cleanup: Use
yarn i18n:clean
monthly - Monitor Quality: Track translation coverage and issues
- Enhanced Extraction: Use enhanced extraction for new features
- Documentation: Keep translation guidelines updated
CI/CD Integration
GitLab CI Integration
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
|
Pre-commit Hooks
Add to .husky/pre-commit
:
1 2 3 4 5 |
|
Troubleshooting
Common Issues
"Found more used translations than in template"
- Run
yarn i18n:extract
to update the template with new strings
"Too many false positives for missing translations"
- Adjust
ignorePatterns
incheckTranslations.cjs
- Review context where strings appear
"Backup files accumulating"
- Cleanup script creates timestamped backups
- Remove old backups manually:
rm template.backup.*.json
"Extraction taking too long"
- The extraction tool includes comprehensive analysis which may take longer on large codebases
- Consider running extraction only when translation strings have been modified
Configuration
Customize detection rules in checkTranslations.cjs
:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
|
Getting Help
- View detailed analysis:
yarn i18n:check
- Test changes safely: Use
--dry-run
flags - Check configuration: Review ignore patterns and limits
- Gradual adoption: Use
--warn-only
during transition
File Structure
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
Advanced Features
Context-Aware Translation Analysis
The enhanced tools can analyze specific locale quality using the unified analyzer:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
Supported Languages: The analyzer supports 27+ languages including European (German, Spanish, French, Italian, Polish, Czech, Estonian, Lithuanian, Latvian, Dutch, Danish, Swedish, Finnish, Norwegian, Slovenian, Bulgarian, Greek), Slavic (Russian, Ukrainian), Middle Eastern (Arabic, Persian), Asian (Thai, Bengali), and Turkic (Azerbaijani, Kyrgyz) languages.
LLM-Powered Translation Improvements
Generate focused prompts for Language Model (LLM) tools like Claude to improve translations:
1 2 |
|
Features:
- Categorized Prompts: Groups translations by type (missing, problematic, buttons, errors, titles)
- Batch Processing: ~30 translations per prompt to avoid context overload
- Direct Editing: Prompts designed for LLMs to directly edit locale files
- Git Versioning: Changes tracked automatically through git
- Context-Rich: Uses enhanced template analysis for better translation quality
Generated Structure:
1 2 3 4 5 6 7 8 |
|
Workflow:
- Generate prompts:
yarn i18n:llm:prepare
- Copy prompt: From relevant
.txt
file inlocales/llm-prompts/
- Paste to LLM: In Claude Code or similar tool
- Direct editing: LLM updates
locales/{lang}.json
directly - Review changes: Use git to see what was modified
- Commit improvements: Standard git workflow
Recommended Order:
- missing - Adds missing translations
- problematic - Fixes obvious quality issues
- errors - Improves user experience
- buttons - Enhances UI consistency
- titles - Polishes terminology
This provides:
- UI-specific translation recommendations: Button text, form labels, navigation elements
- Cultural adaptation suggestions: Appropriate formality levels and local conventions
- Technical terminology optimization: Native terms vs. loanwords, compound words
- Error message tone analysis: Clarity and user-friendliness
- Language-specific grammar checks: Case agreement, verb forms, number handling
Estonian-Specific Analysis
The Estonian analyzer provides specialized checks for:
- Case Agreement: Estonian has 14 cases - the tool checks for proper case usage with variables
- Imperative Forms: Verifies action buttons use appropriate Estonian imperative (da-infinitive)
- Number-Noun Agreement: Estonian has complex singular/plural rules with numbers
- Compound Words: Suggests Estonian compound construction for technical terms
- Error Message Clarity: Ensures error messages are clear and user-friendly
- Native Terminology: Identifies loanwords that could be replaced with native Estonian terms
- Sentence Case: Checks that titles use Estonian sentence case, not English title case
Russian-Specific Analysis
The Russian analyzer focuses on:
- Verb Forms: Imperative mood and aspect selection for action buttons
- Formality Levels: Appropriate formal register for error messages and professional contexts
- Technical Terminology: Balance between international terms and Russian equivalents
- Error Message Clarity: Clear and appropriate error message phrasing
Norwegian-Specific Analysis
The Norwegian analyzer provides specialized checks for:
- Imperative Forms: Norwegian button actions use appropriate imperative forms (lagre, slett, rediger)
- Compound Words: Norwegian preference for compound word construction over separate words
- Gender Agreement: Proper use of Norwegian gender articles (en/ei/et) with nouns
- Error Message Clarity: Clear and appropriate Norwegian error message phrasing
- Native Terminology: Identifies English loanwords that could be replaced with native Norwegian terms
- Sentence Case: Ensures Norwegian sentence case capitalization rather than English title case
Multi-Language Analysis Support
The unified analyzer provides specialized analysis for 27+ languages, each with language-specific grammar and cultural checks:
Germanic Languages:
- German (de): Noun capitalization, compound words, formal/informal address (Sie/du), case system
- Dutch (nl): V2 rule compliance, diminutive forms, modal particles
- Swedish (sv): Definite articles, pitch accent, en/ett gender system
- Danish (da): Definite article suffixes, stΓΈd considerations
Romance Languages:
- Spanish (es): Gender agreement, accent marks, formal/informal address (usted/tΓΊ)
- French (fr): Elision, liaison, gender agreement, accent marks
- Italian (it): Gender agreement, double consonants, formal address (Lei/tu)
Slavic Languages:
- Polish (pl): 7-case system, diacriticals, aspect usage
- Czech (cs): Complex gender system, hΓ‘Δek usage, consonant clusters
- Bulgarian (bg): Cyrillic script, definite article postfixes, aspect usage
- Slovenian (sl): 6-case system, dual number forms (unique among Slavic)
- Ukrainian (uk): Cyrillic specifics, apostrophe usage, avoiding Russianisms
Baltic and Finno-Ugric Languages:
- Estonian (et): 14-case system, imperative forms, compound words, error message clarity
- Lithuanian (lt): 7-case system, dual forms, diminutives
- Latvian (lv): 6-case system, palatalization, long vowels
Other European:
- Greek (el): 4-case system, monotonic accents, Greek alphabet
- Finnish (fi): 15-case system, vowel harmony, consonant gradation
Non-European:
- Arabic (ar): RTL text, dual forms, complex number agreement
- Persian (fa): RTL text, ezafe construction, formal register
- Thai (th): No word spacing, classifiers, tone considerations
- Bengali (bn): Three formality levels, conjunct consonants
- Azerbaijani (az): Vowel harmony, 6-case system
- Kyrgyz (ky): Vowel harmony, Cyrillic variants
Custom Translation Validation
Create custom validation rules for your specific needs:
1 2 3 4 5 6 7 8 9 10 11 |
|
This comprehensive internationalization system ensures high-quality translations while providing developers and translators with the tools and context needed for effective multilingual applications.