mirror of
https://github.com/johannesjo/super-productivity.git
synced 2026-07-18 00:46:45 +00:00
bc3df77e3f
- Add extract and merge modes to manage missing translations - Implement functions to extract missing keys and merge WIP files - Create usage documentation for the translation management script
91 lines
2.7 KiB
Markdown
91 lines
2.7 KiB
Markdown
# I18n Translation Management Script
|
|
|
|
This document describes the usage of the `tools/add-missing-i18n-variables.js` script, which helps manage internationalization (i18n) files for Super Productivity.
|
|
|
|
## Overview
|
|
|
|
The script manages translation files located in `src/assets/i18n/`. The base language is English (`en.json`), and other languages like `de.json` (German), `tr.json` (Turkish), etc., contain translations.
|
|
|
|
The script supports three modes:
|
|
|
|
- **Extract mode**: Creates work-in-progress (WIP) files with missing translations for a specific language.
|
|
- **Merge mode**: Merges translated WIP files back into the main language file.
|
|
- **Legacy mode**: Adds missing keys to all language files (default when no mode is specified).
|
|
|
|
## File Structure
|
|
|
|
- `en.json`: The reference English file with all keys.
|
|
- `{lang}.json`: Main translation files (e.g., `de.json`, `tr.json`).
|
|
- `{lang}-wip.json`: Temporary work-in-progress files containing only missing translations.
|
|
|
|
## Usage
|
|
|
|
### Extract Missing Translations
|
|
|
|
To extract missing translations for a specific language (e.g., Turkish):
|
|
|
|
```bash
|
|
node tools/add-missing-i18n-variables.js extract tr
|
|
```
|
|
|
|
This creates `tr-wip.json` with all keys that exist in `en.json` but are missing or empty in `tr.json`.
|
|
|
|
### Translate WIP File
|
|
|
|
Edit the generated `{lang}-wip.json` file and provide translations for the keys.
|
|
|
|
Example `tr-wip.json`:
|
|
|
|
```json
|
|
{
|
|
"APP": {
|
|
"SKIP_SYNC_WAIT": "Skip waiting for sync"
|
|
},
|
|
"F": {
|
|
"CALDAV": {
|
|
"ISSUE_CONTENT": {
|
|
"DESCRIPTION": "Description"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Merge Translations
|
|
|
|
After translating the WIP file, merge it back into the main language file:
|
|
|
|
```bash
|
|
node tools/add-missing-i18n-variables.js merge tr
|
|
```
|
|
|
|
This:
|
|
|
|
- Merges translations from `tr-wip.json` into `tr.json`
|
|
- Maintains the same key order as `en.json`
|
|
- Validates that all keys are present
|
|
- Deletes the `tr-wip.json` file
|
|
|
|
### Legacy Mode (Update All Files)
|
|
|
|
To add missing keys to all language files at once (preserving existing translations):
|
|
|
|
```bash
|
|
node tools/add-missing-i18n-variables.js
|
|
```
|
|
|
|
This updates all `{lang}.json` files to include any new keys from `en.json`, placing them in the same order.
|
|
|
|
## Workflow Example
|
|
|
|
1. New features are added, updating `en.json` with new keys.
|
|
2. Run extract for your language: `node tools/add-missing-i18n-variables.js extract de`
|
|
3. Translate the keys in `de-wip.json`.
|
|
4. Run merge: `node tools/add-missing-i18n-variables.js merge de`
|
|
5. Submit a pull request with the updated `de.json`.
|
|
|
|
## Notes
|
|
|
|
- The script preserves the order of keys to match `en.json`.
|
|
- Empty strings in translation files trigger English fallback.
|
|
- WIP files are temporary and it would be deleted via the merge command.
|