docs: add translation documentation and fix SystemSettings tests
Co-authored-by: Wikid82 <176516789+Wikid82@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
205
CONTRIBUTING_TRANSLATIONS.md
Normal file
205
CONTRIBUTING_TRANSLATIONS.md
Normal file
@@ -0,0 +1,205 @@
|
||||
# Contributing Translations
|
||||
|
||||
Thank you for your interest in translating Charon! This guide will help you contribute translations in your language.
|
||||
|
||||
## Overview
|
||||
|
||||
Charon uses [i18next](https://www.i18next.com/) and [react-i18next](https://react.i18next.com/) for internationalization (i18n). All translations are stored in JSON files organized by language.
|
||||
|
||||
## Supported Languages
|
||||
|
||||
Currently, Charon supports the following languages:
|
||||
|
||||
- 🇬🇧 English (`en`) - Default
|
||||
- 🇪🇸 Spanish (`es`)
|
||||
- 🇫🇷 French (`fr`)
|
||||
- 🇩🇪 German (`de`)
|
||||
- 🇨🇳 Chinese (`zh`)
|
||||
|
||||
## File Structure
|
||||
|
||||
Translation files are located in `frontend/src/locales/`:
|
||||
|
||||
```plaintext
|
||||
frontend/src/locales/
|
||||
├── en/
|
||||
│ └── translation.json (Base translation - always up to date)
|
||||
├── es/
|
||||
│ └── translation.json
|
||||
├── fr/
|
||||
│ └── translation.json
|
||||
├── de/
|
||||
│ └── translation.json
|
||||
└── zh/
|
||||
└── translation.json
|
||||
```
|
||||
|
||||
## How to Contribute
|
||||
|
||||
### Adding a New Language
|
||||
|
||||
1. **Create a new language directory** in `frontend/src/locales/` with the ISO 639-1 language code (e.g., `pt` for Portuguese)
|
||||
|
||||
2. **Copy the English translation file** as a starting point:
|
||||
```bash
|
||||
cp frontend/src/locales/en/translation.json frontend/src/locales/pt/translation.json
|
||||
```
|
||||
|
||||
3. **Translate all strings** in the new file, keeping the JSON structure intact
|
||||
|
||||
4. **Update the i18n configuration** in `frontend/src/i18n.ts`:
|
||||
```typescript
|
||||
import ptTranslation from './locales/pt/translation.json'
|
||||
|
||||
const resources = {
|
||||
en: { translation: enTranslation },
|
||||
es: { translation: esTranslation },
|
||||
// ... other languages
|
||||
pt: { translation: ptTranslation }, // Add your new language
|
||||
}
|
||||
```
|
||||
|
||||
5. **Update the Language type** in `frontend/src/context/LanguageContextValue.ts`:
|
||||
```typescript
|
||||
export type Language = 'en' | 'es' | 'fr' | 'de' | 'zh' | 'pt' // Add new language
|
||||
```
|
||||
|
||||
6. **Update the LanguageSelector component** in `frontend/src/components/LanguageSelector.tsx`:
|
||||
```typescript
|
||||
const languageOptions: { code: Language; label: string; nativeLabel: string }[] = [
|
||||
// ... existing languages
|
||||
{ code: 'pt', label: 'Portuguese', nativeLabel: 'Português' },
|
||||
]
|
||||
```
|
||||
|
||||
7. **Test your translation** by running the application and selecting your language
|
||||
|
||||
8. **Submit a pull request** with your changes
|
||||
|
||||
### Improving Existing Translations
|
||||
|
||||
1. **Find the translation file** for your language in `frontend/src/locales/{language-code}/translation.json`
|
||||
|
||||
2. **Make your improvements**, ensuring you maintain the JSON structure
|
||||
|
||||
3. **Test the changes** by running the application
|
||||
|
||||
4. **Submit a pull request** with a clear description of your improvements
|
||||
|
||||
## Translation Guidelines
|
||||
|
||||
### General Rules
|
||||
|
||||
1. **Preserve placeholders**: Keep interpolation variables like `{{count}}` intact
|
||||
- ✅ `"activeHosts": "{{count}} activo"`
|
||||
- ❌ `"activeHosts": "5 activo"`
|
||||
|
||||
2. **Maintain JSON structure**: Don't add or remove keys, only translate values
|
||||
- ✅ Keep all keys exactly as they appear in the English file
|
||||
- ❌ Don't rename keys or change nesting
|
||||
|
||||
3. **Use native language**: Translate to what native speakers would naturally say
|
||||
- ✅ "Configuración" (Spanish for Settings)
|
||||
- ❌ "Settings" (leaving it in English)
|
||||
|
||||
4. **Keep formatting consistent**: Respect capitalization and punctuation conventions of your language
|
||||
|
||||
5. **Test your translations**: Always verify your translations in the application to ensure they fit in the UI
|
||||
|
||||
### Translation Keys
|
||||
|
||||
The translation file is organized into logical sections:
|
||||
|
||||
- **`common`**: Frequently used UI elements (buttons, labels, actions)
|
||||
- **`navigation`**: Menu and navigation items
|
||||
- **`dashboard`**: Dashboard-specific strings
|
||||
- **`settings`**: Settings page strings
|
||||
- **`proxyHosts`**: Proxy hosts page strings
|
||||
- **`certificates`**: Certificate management strings
|
||||
- **`auth`**: Authentication and login strings
|
||||
- **`errors`**: Error messages
|
||||
- **`notifications`**: Success/failure notifications
|
||||
|
||||
### Example Translation
|
||||
|
||||
Here's an example of translating a section from English to Spanish:
|
||||
|
||||
```json
|
||||
// English (en/translation.json)
|
||||
{
|
||||
"common": {
|
||||
"save": "Save",
|
||||
"cancel": "Cancel",
|
||||
"delete": "Delete"
|
||||
}
|
||||
}
|
||||
|
||||
// Spanish (es/translation.json)
|
||||
{
|
||||
"common": {
|
||||
"save": "Guardar",
|
||||
"cancel": "Cancelar",
|
||||
"delete": "Eliminar"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Testing Translations
|
||||
|
||||
### Manual Testing
|
||||
|
||||
1. Start the development server:
|
||||
```bash
|
||||
cd frontend
|
||||
npm run dev
|
||||
```
|
||||
|
||||
2. Open the application in your browser (usually `http://localhost:5173`)
|
||||
|
||||
3. Navigate to **Settings** → **System** → **Language**
|
||||
|
||||
4. Select your language from the dropdown
|
||||
|
||||
5. Navigate through the application to verify all translations appear correctly
|
||||
|
||||
### Automated Testing
|
||||
|
||||
Run the i18n tests to verify your translations:
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm test -- src/__tests__/i18n.test.ts
|
||||
```
|
||||
|
||||
## Building the Application
|
||||
|
||||
Before submitting your PR, ensure the application builds successfully:
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run build
|
||||
```
|
||||
|
||||
## RTL (Right-to-Left) Languages
|
||||
|
||||
If you're adding a Right-to-Left language (e.g., Arabic, Hebrew):
|
||||
|
||||
1. Add the language code to the RTL check in `frontend/src/context/LanguageContext.tsx`
|
||||
2. Test the UI thoroughly to ensure proper RTL layout
|
||||
3. You may need to update CSS for proper RTL support
|
||||
|
||||
## Questions or Issues?
|
||||
|
||||
If you have questions or run into issues while contributing translations:
|
||||
|
||||
1. Open an issue on GitHub with the `translation` label
|
||||
2. Describe your question or problem clearly
|
||||
3. Include the language you're working on
|
||||
|
||||
## Translation Status
|
||||
|
||||
To check which translations need updates, compare your language file with the English (`en/translation.json`) file. Any keys present in English but missing in your language file should be added.
|
||||
|
||||
## Thank You!
|
||||
|
||||
Your contributions help make Charon accessible to users worldwide. Thank you for taking the time to improve the internationalization of this project!
|
||||
Reference in New Issue
Block a user