po-fill

Extract → Translate (OpenAI) → Apply for PO files with AI translation

A powerful Node.js tool for automatically translating PO (gettext) files using OpenAI's GPT models. Supports batch processing, language detection, and comprehensive reporting.

Features

• Extract: Extract translatable strings from PO files
• Translate: Use OpenAI GPT models for AI-powered translation
• Apply: Apply translations back to PO files with validation
• Autofill: Complete workflow in one command
• Language Lock: Ensures translations stay in target language
• Batch Processing: Efficient handling of large files
• Comprehensive Reporting: Detailed logs and error tracking

Installation

Global installation (recommended)

npm install -g po-fill

Local installation

npm install po-fill

Setup

1. Set your OpenAI API key:

export OPENAI_API_KEY=sk-your-api-key-here

2. Install dependencies:

npm install

Usage

Command Line Interface

# Extract translatable strings
po-fill extract <input.po> <translations.jsonl> [--full]

# Translate using OpenAI
po-fill translate <input.po> <in.jsonl> <out.jsonl> [--to "Language"] [--batch N] [--model MODEL] [--temp X] [--effort minimal|low|medium|high] [--no-spinner]

# Apply translations
po-fill apply <input.po> <in.jsonl> <output.po> [--to "Language"] [--lang-code XX[_YY]]

# Complete workflow
po-fill autofill <input.po> <output.po> [--full] [--to "Language"] [--lang-code XX[_YY]] [--batch N] [--model MODEL] [--temp X] [--effort minimal|low|medium|high] [--no-spinner]

Options

• --full: Extract ALL msgid entries (not just empty ones)
• --to "Language": Target language for translation
• --lang-code XX[_YY]: Update PO header Language field (e.g., fi, fi_FI)
• --batch N: Batch size for translation (default: 100)
• --model MODEL: OpenAI model to use (default: gpt-5-mini)
• --temp X: Temperature setting for AI model
• --effort: Reasoning effort level for GPT-5 models
• --no-spinner: Disable progress spinner

Examples

# Extract Finnish translations from English PO
po-fill extract en_GB.po fi_translations.jsonl --full

# Translate to Finnish using GPT-5
po-fill translate en_GB.po fi_translations.jsonl fi_filled.jsonl --to "Finnish" --model gpt-5

# Apply translations and update headers
po-fill apply en_GB.po fi_filled.jsonl fi.po --to "Finnish" --lang-code fi

# Complete workflow in one command
po-fill autofill en_GB.po fi.po --full --to "Finnish" --lang-code fi --model gpt-5-mini

Supported Models

• GPT-5: gpt-5, gpt-5-mini, gpt-5-nano
• Fallback Support: Automatic fallback for unsupported parameters
• Language Lock: Prevents language drift with automatic fix passes

JSONL Format

The tool uses JSONL (JSON Lines) format for intermediate files:

{"msgctxt": null, "msgid": "Hello", "pluralIndex": 0, "src": "Hello", "tgt": ""}
{"msgctxt": "context", "msgid": "World", "pluralIndex": 0, "src": "World", "tgt": ""}

Requirements

• Node.js 16.0.0 or higher
• OpenAI API key
• Dependencies: gettext-parser, openai

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Support

For issues and questions, please check the GitHub repository or create an issue.