AI-based Translation System for OpenStack

A lightweight, user-friendly AI translation system for OpenStack i18n. This tool helps contributors translate `.pot` / `.po` files into 54 languages using CPU-friendly LLMs such as **Ollama**, as well as GPT, Claude, and Gemini.

If you're new to OpenStack i18n, see the official OpenStack i18n guide.

Requirements

• Python 3.10 is needed
• Designed for local and CI environments

Quick Start (5 steps)

The fastest way to run your first translation.

By default, this system translates the nova project files into Korean (ko_KR) and Japanese (ja) using the llama3.2:3b model via Ollama. You can customize the target project, model, and language in config.yaml (see Choose Your Options below).

Step 1 — Clone the repository

git clone https://github.com/openstack-kr/knu_i18n_2025.git
cd knu_i18n_2025

Step 2 — Install dependencies

Option A) Use tox (recommended)

# if you trouble in upgrading pip, we recommend to use venv
python -m pip install --upgrade pip
pip install tox

# Install Ollama
# For Linux:
curl -fsSL https://ollama.com/install.sh | sh
# For other operating systems (Windows, macOS):
# Please visit https://ollama.com/download and follow the installation instructions

Option B) Run locally

# if you trouble in upgrading pip, we recommend to use venv
python -m pip install --upgrade pip

# Install Ollama
# For Linux:
curl -fsSL https://ollama.com/install.sh | sh
# For other operating systems (Windows, macOS):
# Please visit https://ollama.com/download and follow the installation instructions

pip install -r requirements.txt

Step 3 — Run translation

This will translate the file specified in config.yaml using the configured model and language.

tox -e i18n -vv
# or
bash local.sh

What's happening:

• The system reads your target .pot or .po file from ./data/target/{lang} directory
• Uses the specified model (default: llama3.2:3b via Ollama)
• Translates into your chosen languages (default: ko_KR, ja)
• Outputs translated .po files to ./po/{model}/{lang}/ directory

Step 4 — Human Review

After AI translation, human review is essential to ensure accuracy and context appropriateness. AI translations are drafts that require human verification before production use.

Open the generated .po file in ./po/{model}/{lang}/ directory and review the translations manually for technical accuracy, natural language flow, and consistency with existing translations.

Step 5 — Merge your translation to origin po

After reviewing AI translation, merge your reviewed translations back to the original .po file:

tox -e i18n-merge -vv
# or
python merge_po.py --config config.yaml

This will merge your reviewed translations and save the final result to ./data/result/{lang} directory.

Choose Your Options

You can customize target file, model, language, and performance settings in config.yaml

Choose Target File

How it works:

1. Place your target .pot or .po file in the ./data/target/{lang} directory
2. Specify the filename in config.yaml:

files:
  # Set target_file to translate (must be placed under ./data/target/{lang})
  target_file: "example_nova.po"

File processing flow:

• Input: ./data/target/{lang}/{target_file}.po or ./data/target/{lang}/{target_file}.pot
• Intermediate outputs:
  • Extracted POT: ./pot/{target_file}.pot
  • AI translations: ./po/{model}/{lang}/{target_file}.po
• Final output: ./data/result/{lang}/{target_file}.po (merged translation)

Downloading files from Weblate:

You can manually download the latest translated POT or PO files directly from the Weblate interface.

Steps:

1. Go to the Weblate translation dashboard for the project Example
2. Select the project (e.g., Nova, Horizon, etc.)
3. Navigate to: project → languages → <Your Language>
4. Click "Download translation"
5. Save the downloaded file to the ./data/target/{lang}/ directory
6. Update the target_file name in config.yaml

Choose Your Language

Please insert your language code from this link. We support 54 languages

languages:
  # When running local.sh, please choose exactly ONE language.
  # When running ci.sh, you can specify MULTIPLE languages.
  - "ko_KR"
  - "ja"

Choose Your Model

Open-source models (default)

Uses Ollama. Browse available models HERE.

Closed-source models (GPT / Claude / Gemini)

When using closed-source model, edit the backend using llm.mode: [ollama (default), gpt, claude, gemini]

# You can tune these arguments for performance / partial translation:
llm:
  model: "llama3.2:3b"
  mode: "ollama"   # Choose your LLM mode: `ollama` (default), `gpt`, `claude`, `gemini`
  workers: 1       # number of parallel threads (default: 1)
  start: 0         # entry index range to translate (default: 0 ~ all)
  end: -1
  batch_size: 5    # entries per LLM call (default: 5)

CI Integration

For automated translation in OpenStack's Zuul CI environment, use the provided CI script:

# Ensure you have completed Step 2 — Install dependencies before running this
bash ci.sh

⚠️ For detailed instructions on configuring config.yaml (git settings) and understanding current limitations, please refer to the CI.md.

The script automatically uses config.yaml by default, or you can specify a different config file:

bash ci.sh my-config.yaml

What ci.sh does:

The script runs a 3-step pipeline:

1. Find changed content: Runs commit_diff.py to detect added or edited msgid entries in your target file and extracts them to a .pot file
2. Translate: Executes translate.py to translate the extracted entries using your configured model
3. Merge: Uses merge_po.py to merge AI-translated content back into the original .po file

Results are saved to ./data/result/{lang}/{target_file}.po

Usage in CI pipeline:

# Example Zuul job configuration
- job:
    name: translate-pot-files
    run: playbooks/translate.yaml

# In your playbook:
- name: Run AI Translation
    shell: bash ci.sh

The CI workflow is optimized to translate only changed content, making it efficient for continuous integration pipelines.

How the System Works (Simple Overview)

The system automatically:

• Loads the .pot file
• Splits text into batches
• Applies the general prompt or a language-specific prompt (if available)
• Adds few-shot examples when reference translations exist
• Generates draft .po translations

Draft translations are then pushed to Gerrit → reviewed → synced to Weblate. For full architecture details, see PAPER.md.

Assist in Improving Translation Quality

You can tune two major components:

• Few-shot examples (/examples/)
• Language-specific prompts (/prompts/)

See CONTRIBUTING.md to learn how you can contribute.

Code Formatting

Run PEP8 style checks:

tox -e pep8

Auto-fix style issues:

autopep8 --in-place --aggressive --aggressive -r .

Team

• Lee Juyeong - Project Lead
• Oh Jiwoo
• Jo Taeho
• Chun Sihyeon
• Hwang Jiyoung