| name | csv-translator |
| description | Specialized skill for translating large CSV files. It follows a multi-step process of planning, counting lines, splitting large files into manageable chunks, translating chunks, merging, and finally importing translations into Android resource files. Use when the user needs to translate a CSV file, especially large ones. |
CSV Translator Workflow
This skill provides a robust way to translate CSV files while managing context window limits by splitting large files into smaller chunks.
Workflow Steps
0. Discovery & Extraction (Optional)
Before translating, you may need to identify what needs translation:
- Find Untranslated Strings: Use
node scripts/export_untranslated.cjs <res_dir> [ref_res_dir] to export missing translations to untranslated_strings.csv.
- Find Hardcoded Strings: Use
node scripts/extract_hardcoded_strings.cjs <src_dir> to find UI text in code that should be moved to strings.xml.
- Find Unused Strings: Use
node scripts/find_unused_strings.cjs <module_name> to clean up resources before exporting.
1. Planning & Analysis
- Identify Target: Determine the CSV file to be translated and the target language(s).
- Count Lines: Use `run_shell_command` with `wc -l` to determine the size of the file.
- Set Chunk Size: Based on the file size and complexity, decide on a target number of lines per chunk (default recommendation: 100-200 lines).
2. Splitting (If Large)
- If the file exceeds the manageable limit, split it into smaller files.
- Use a script (e.g., `scripts/split_csv.cjs`) to ensure data integrity (keeping headers in each chunk or handling them correctly).
- Recursive Check: If a split file is still considered too large for a single translation turn, split it further.
3. Translation
- Translate each chunk individually.
- Maintain the CSV structure and ensure that keys/IDs (if any) are preserved.
- Use a consistent tone and terminology across all chunks.
- DO NOT manually escape special characters (like `'` or `"`) in the CSV; the import script handles this automatically.
4. Merging
- Once all chunks are translated, merge them back into a single final CSV file.
- Use a script (e.g., `scripts/merge_csv.cjs`) to combine the files, ensuring only one header row exists.
5. Importing (Android Specific)
- Use `scripts/import_translations.cjs` to automatically take the merged translations and update the project's `strings.xml` files.
- Command: `node scripts/import_translations.cjs <merged_csv_path> <res_directory>`
6. Validation
- Verify the final CSV file structure and line count matches the original.
- Run a build check (e.g., `./gradlew assembleDebug`) to ensure the imported strings don't break the build.
Guardrails
- Preserve Structure: Never change the number of columns or the meaning of specific fields (like IDs).
- Header Integrity: Ensure the header row is handled correctly during splitting and merging.
- Encoding: Maintain UTF-8 encoding throughout the process.
- Double-Escaping Prevention: Always provide raw text in the CSV. The import script will convert raw quotes into Android-compatible escapes (e.g., `can't` -> `can\'t`).
7. Cleanup & Git
- Ensure you do NOT commit intermediate CSV files (e.g., untranslated strings, chunks, merged files, formatted files) to the repository.
- Delete these temporary files once the import is successfully validated, or ensure they are excluded via `.gitignore`.
