A command-line tool to translate filenames from one language to another using Google Translate.
- Translates filenames (preserving extensions)
- Renames directories too
- Recursive processing of subdirectories
- Auto-detects source language if not specified
- Dry-run mode to preview changes
- Handles filename conflicts with
-1,-2,-3suffixes - Sanitizes invalid filename characters
pip install -r requirements.txt
python transnamer.py --helpbuild.batThis creates TransNamer.exe in the dist folder.
TransNamer --input <directory> [--from <lang>] [--to <lang>] [--dry-run]
| Argument | Short | Required | Default | Description |
|---|---|---|---|---|
--input |
-i |
Yes | - | Input directory to process |
--from |
-f |
No | auto | Source language code (e.g., ja, zh, ko) |
--to |
-t |
No | en | Target language code |
--dry-run |
-d |
No | - | Preview translations without renaming |
--workers |
-w |
No | 10 | Number of concurrent translation workers |
Common language codes:
en- Englishja- Japanesezh- Chinese (Simplified)zh-TW- Chinese (Traditional)ko- Koreanes- Spanishfr- Frenchde- Germanru- Russian
For a full list, see Google Translate language codes.
TransNamer --input ./anime_folder --from ja --to en --dry-runTransNamer --input ./mixed_files --to enTransNamer --input ./documents --from zh --to es- Files and directories are processed recursively
- Directories are renamed after files (deepest directories first) to avoid path issues
- If a translated filename already exists, a numeric suffix is added (
-1,-2, etc.) - Invalid filename characters are replaced with underscores
- The original file extension is always preserved
- Translation uses concurrent requests (10 workers by default)
- Duplicate names are translated only once
- ASCII-only filenames are automatically skipped
- Use
--workersto tune concurrency (lower if rate-limited, higher for speed)
- Python 3.10+
- Internet connection (for Google Translate API)