Skip to content

Commit c9205de

Browse files
committed
fix(tests): update login credentials in automatic test configuration for improved security
1 parent 3bcb05f commit c9205de

File tree

3 files changed

+481
-1
lines changed

3 files changed

+481
-1
lines changed
Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
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

Comments
 (0)