OpenParable
Skip to content
← Back to skills

CSV Translator

Documents
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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/pass-with-high-score/blockads-android/blob/HEAD/.agent/skills/csv-translator/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/csv-translator, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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