# CSV Translator

> CSV Translator is an Agent Skill for documents published in the pass-with-high-score/blockads-android repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

- Skill name: `csv-translator`
- Category: [Documents](https://www.openparable.com/skill/documents/1)
- Source: https://github.com/pass-with-high-score/blockads-android/blob/HEAD/.agent/skills/csv-translator/SKILL.md
- Repository: pass-with-high-score/blockads-android (1,564 GitHub stars when collected)

## SKILL.md

# 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\`.

---

Source: https://www.openparable.com/skill/documents/csv-translator (OpenParable). Cite the canonical URL above.