|
| 1 | +# Translation Agent Instructions |
| 2 | + |
| 3 | +Instructions for AI agents and automated contributors working on translations in the Better Together Community Engine. |
| 4 | + |
| 5 | +## Project Context |
| 6 | + |
| 7 | +- **Rails Engine**: Better Together Community Engine with host application pattern |
| 8 | +- **Supported Locales**: en (source), es, fr, uk |
| 9 | +- **Docker Environment**: All commands require `bin/dc-run` for database/service access |
| 10 | +- **I18n Framework**: Rails i18n with i18n-tasks gem for management |
| 11 | + |
| 12 | +## Core Translation Principles |
| 13 | + |
| 14 | +### Technical Requirements |
| 15 | +- **Preserve YAML structure exactly** - Any syntax error breaks the entire locale file |
| 16 | +- **Maintain Rails i18n conventions** - Keep `%{variable}` interpolation intact |
| 17 | +- **Never modify symbolic references** - Leave `:activerecord.models.user` unchanged |
| 18 | +- **Respect locale hierarchy** - Follow Rails namespace conventions (`better_together.*`) |
| 19 | + |
| 20 | +### Translation Strategy |
| 21 | +1. **Security first**: Run `bin/dc-run bundle exec brakeman --quiet --no-pager` before translation work |
| 22 | +2. **User-facing priority**: Translate authentication, navigation, forms, and error messages first |
| 23 | +3. **Consistency over perfection**: Establish terminology early and maintain throughout |
| 24 | +4. **Cultural appropriateness**: Research proper terms and formality levels for target culture |
| 25 | + |
| 26 | +## Systematic Translation Process |
| 27 | + |
| 28 | +### 1. Assessment Phase |
| 29 | +```bash |
| 30 | +# Check translation completeness |
| 31 | +bin/dc-run i18n-tasks missing {locale} |
| 32 | + |
| 33 | +# Find English strings in target locale files |
| 34 | +grep -c "sign_in\|login\|register\|confirm" config/locales/{locale}.yml |
| 35 | + |
| 36 | +# Identify high-impact untranslated sections |
| 37 | +grep -n "better_together:\|devise:\|activerecord:" config/locales/{locale}.yml |
| 38 | +``` |
| 39 | + |
| 40 | +### 2. Translation Phase |
| 41 | + |
| 42 | +#### Priority Order: |
| 43 | +1. **Devise Authentication** (`devise:`) - Complete login/registration flows |
| 44 | +2. **ActiveRecord Models** (`activerecord:`) - Model attributes and relationships |
| 45 | +3. **Better Together Core** (`better_together:`) - Main application features |
| 46 | +4. **Navigation & UI** (`navbar:`, `navigation:`) - User interface elements |
| 47 | +5. **Error Handling** (`errors:`, `flash:`) - User feedback messages |
| 48 | +6. **Form Helpers** (`helpers:`, `hints:`) - Form labels and instructions |
| 49 | + |
| 50 | +#### Translation Approach: |
| 51 | +- **Work in logical chunks** - Complete related features together (e.g., all conversation features) |
| 52 | +- **Use search patterns** to find remaining English strings systematically |
| 53 | +- **Verify interpolation** - Ensure `%{platform_name}`, `%{user_name}` etc. are preserved |
| 54 | +- **Check pluralization** - Handle `one:`, `other:` (and `few:`, `many:` for complex languages) |
| 55 | + |
| 56 | +### 3. Quality Assurance |
| 57 | +```bash |
| 58 | +# Validate YAML syntax |
| 59 | +bin/dc-run ruby -c config/locales/{locale}.yml |
| 60 | + |
| 61 | +# Check translation health |
| 62 | +bin/dc-run i18n-tasks health |
| 63 | + |
| 64 | +# Normalize formatting |
| 65 | +bin/dc-run i18n-tasks normalize |
| 66 | +``` |
| 67 | + |
| 68 | +## Language-Specific Guidelines |
| 69 | + |
| 70 | +### Ukrainian (uk) |
| 71 | +- **Formality**: Use formal "Ви" form in interface |
| 72 | +- **Technical terms**: Mix established Ukrainian IT terms with necessary anglicisms |
| 73 | +- **Grammar**: Handle complex case system appropriately |
| 74 | +- **Pluralization**: Use `one:`, `few:`, `many:`, `other:` forms per Ukrainian rules |
| 75 | + |
| 76 | +**Key Terminology:** |
| 77 | +```yaml |
| 78 | +Platform: Платформа |
| 79 | +Community: Спільнота |
| 80 | +Conversation: Розмова |
| 81 | +User: Користувач |
| 82 | +Person: Особа |
| 83 | +Sign in: Увійти |
| 84 | +Register: Зареєструватися |
| 85 | +``` |
| 86 | +
|
| 87 | +### Spanish (es) |
| 88 | +- **Formality**: Use formal register appropriate for business/platform context |
| 89 | +- **Gender**: Handle noun gender agreement correctly |
| 90 | +- **Regional neutrality**: Avoid region-specific terms, use international Spanish |
| 91 | +- **Technical terms**: Prefer Spanish equivalents where well-established |
| 92 | +
|
| 93 | +### French (fr) |
| 94 | +- **Formality**: Use "vous" form, appropriate business French |
| 95 | +- **Gender agreement**: Ensure proper masculine/feminine forms |
| 96 | +- **Technical terminology**: Use established French tech terms over anglicisms |
| 97 | +- **Cultural context**: Respect French linguistic preferences |
| 98 | +
|
| 99 | +## Rails Engine Translation Patterns |
| 100 | +
|
| 101 | +### ActiveRecord Attributes |
| 102 | +```yaml |
| 103 | +activerecord: |
| 104 | + attributes: |
| 105 | + better_together/model_name: |
| 106 | + field_name: Translated Field Name |
| 107 | + lock_version: Version de verrouillage # Technical field |
| 108 | + created_at: Créé le # Timestamp |
| 109 | +``` |
| 110 | +
|
| 111 | +### Better Together Features |
| 112 | +```yaml |
| 113 | +better_together: |
| 114 | + conversations: |
| 115 | + index: |
| 116 | + title: Conversations # Page title |
| 117 | + new: Nouvelle conversation # Action button |
| 118 | + form: |
| 119 | + participants: Participants # Form label |
| 120 | + message: Message # Form field |
| 121 | +``` |
| 122 | +
|
| 123 | +### Navigation Elements |
| 124 | +```yaml |
| 125 | +navbar: |
| 126 | + sign_in: Se connecter |
| 127 | + settings: Paramètres |
| 128 | + my_profile: Mon profil |
| 129 | +navigation: |
| 130 | + header: |
| 131 | + events: Événements |
| 132 | + exchange_hub: Centre d'échange |
| 133 | +``` |
| 134 | +
|
| 135 | +## Validation and Testing |
| 136 | +
|
| 137 | +### Required Checks |
| 138 | +- **YAML syntax validation** - File must parse without errors |
| 139 | +- **Interpolation preservation** - All `%{variable}` placeholders intact |
| 140 | +- **Key completeness** - No missing required translation keys |
| 141 | +- **Pluralization correctness** - Proper plural forms for target language |
| 142 | + |
| 143 | +### Testing Commands |
| 144 | +```bash |
| 145 | +# Test locale file loading |
| 146 | +bin/dc-run rails runner "I18n.locale = :uk; I18n.t('devise.sessions.new.sign_in')" |
| 147 | +
|
| 148 | +# Check for missing translations |
| 149 | +bin/dc-run i18n-tasks missing uk |
| 150 | +
|
| 151 | +# Verify application functionality |
| 152 | +bin/dc-run bundle exec rspec spec/features/authentication_spec.rb |
| 153 | +``` |
| 154 | + |
| 155 | +## Documentation Integration |
| 156 | + |
| 157 | +### Required Documentation Updates |
| 158 | +When completing translations for a new locale: |
| 159 | + |
| 160 | +1. **Update README** with supported language information |
| 161 | +2. **Document cultural considerations** for complex translation choices |
| 162 | +3. **Add locale-specific user guides** if needed |
| 163 | +4. **Update deployment docs** with locale configuration |
| 164 | + |
| 165 | +### Translation Notes |
| 166 | +Document complex translation decisions: |
| 167 | + |
| 168 | +```yaml |
| 169 | +# Example documentation in locale file comments |
| 170 | +# Note: "Community" translated as "Спільнота" rather than "Громада" |
| 171 | +# to emphasize collaborative/social aspect over administrative division |
| 172 | +better_together: |
| 173 | + community: |
| 174 | + name: Спільнота |
| 175 | +``` |
| 176 | + |
| 177 | +## Error Prevention |
| 178 | + |
| 179 | +### Common Pitfalls |
| 180 | +1. **YAML formatting errors** - Always validate syntax after changes |
| 181 | +2. **Missing interpolation variables** - Search and replace carefully |
| 182 | +3. **Inconsistent terminology** - Maintain translation glossary |
| 183 | +4. **Cultural inappropriate terms** - Research proper usage in target culture |
| 184 | +5. **Incomplete translations** - Don't leave sections partially translated |
| 185 | + |
| 186 | +### Prevention Strategies |
| 187 | +- **Use search patterns** to systematically find English strings |
| 188 | +- **Validate incrementally** - Check YAML syntax frequently during translation |
| 189 | +- **Test in context** - Verify translations work in actual application usage |
| 190 | +- **Maintain terminology list** - Keep consistent translations for repeated terms |
| 191 | + |
| 192 | +## Integration with Better Together Standards |
| 193 | + |
| 194 | +### Security Compliance |
| 195 | +- Run Brakeman security scan before translation work |
| 196 | +- Never introduce security vulnerabilities through translation changes |
| 197 | +- Validate that translated user inputs follow same security patterns |
| 198 | + |
| 199 | +### Testing Requirements |
| 200 | +- All translation changes must maintain existing test coverage |
| 201 | +- Add locale-specific tests for complex cultural adaptations |
| 202 | +- Verify internationalized features work correctly in target locale |
| 203 | + |
| 204 | +### Code Review Standards |
| 205 | +- Include native speaker review when possible |
| 206 | +- Document rationale for complex translation choices |
| 207 | +- Ensure translations align with platform's tone and brand |
| 208 | + |
| 209 | +## Automation Support |
| 210 | + |
| 211 | +### Recommended Tools |
| 212 | +```bash |
| 213 | +# I18n management |
| 214 | +bin/dc-run i18n-tasks add-missing # Add missing keys |
| 215 | +bin/dc-run i18n-tasks remove-unused # Clean unused keys |
| 216 | +bin/dc-run i18n-tasks translate-missing # Auto-translate with service |
| 217 | +
|
| 218 | +# Quality checks |
| 219 | +bin/dc-run i18n-tasks health # Complete health check |
| 220 | +bin/dc-run i18n-tasks check-consistent-interpolations |
| 221 | +``` |
| 222 | + |
| 223 | +### CI/CD Integration |
| 224 | +Translation work should integrate with existing CI pipelines: |
| 225 | +- YAML syntax validation in PR checks |
| 226 | +- Translation completeness verification |
| 227 | +- Automated testing with new locale configurations |
| 228 | + |
| 229 | +This guide ensures consistent, high-quality translations that maintain the technical integrity and user experience of the Better Together Community Engine across all supported languages. |
0 commit comments