transctl 1.0.1

A command-line tool for managing application localization and generating translations using machine translation services.

transctl

A pragmatic localization CLI ⚙️

transctl is a command-line tool for managing application translation workflows. It scans source files, extracts translatable content, translates it using a configured machine translation provider, and writes translated output files according to your project structure.

The tool maintains a local manifest and translation memory to avoid unnecessary retranslations across runs.

---

Installation

Requires Python ≥ 3.11.

Install from PyPI:

pip install transctl

---

Quick Start

Initialize a configuration file:

transctl init

Run the translation workflow:

transctl run

That’s the minimal happy path.

Use:

transctl --help

to explore additional commands.

---

What It Does

transctl:

• Scans configured resource directories
• Extracts translatable content from files
• Translates content into one or more target locales
• Writes translated output files (never overwrites the source file)
• Skips unchanged files using a generated manifest.json
• Maintains a local SQLite-based translation memory
• Supports optional glossary injection
• Supports placeholder protection using {{placeholder}} syntax

---

Avoiding Unnecessary Retranslations

Two mechanisms are used:

1. Translation Manifest (manifest.json)

After each run, a manifest.json file is generated automatically.
It tracks file state to skip unchanged files in subsequent runs.

If the manifest is deleted or purged, files may be reprocessed.

---

2. Local Translation Memory (SQLite)

A local SQLite database stores translated segments to prevent repeated translation of identical content across runs.

• Automatically created and maintained
• Oldest entries may be pruned when the file grows too large
• Can be purged manually via transctl purge

If deleted, memory will rebuild over time.

---

Configuration

The .transctl.toml file is required for operation.

If transctl init is executed and a configuration file already exists, no changes are made.

---

Example Configuration

[locale]
source = "en"
targets = [
    "fr",
]

[engine]
provider = "deepl"

[resources.html]
dirs = [
    { path = "templates/*", layout = "along-sided" }
]

[resources.json]
dirs = [
    { path = "locales/[source].*.json"}
]

---

Locale

[locale]
source = "en"
targets = ["fr"]

• source — source language
• targets — one or more target languages

---

Engine

[engine]
provider = "deepl"

Supported providers:

• deepl
• azure

Engine-specific parameters can be provided interactively or via CLI flags.

Note: The auth_key of all engines must be provided as an environment variable.

DeepL

Required parameters: None

Example (non-interactive):

transctl init -y \
  -e deepl

Azure

Required parameters:

• region — Azure resource region

Example (non-interactive):

transctl init -y \
  -e azure \
  --param region=$AZURE_REGION

---

Resources

Resources define what files should be translated.

Currently supported:

• HTML
• JSON

Example:

[resources.json]
dirs = [
    { path = "locales/*", layout = "along-sided" },
]

---

Layout Behavior

layout determines where translated files are written.

Allowed values:

• along-sided
• by-language

If omitted, the default behavior is equivalent to along-sided. Note that layout="" is not valid and will result in an error.

along-sided

If the original file is:

i18n.json

The translated file becomes:

fr_i18n.json

---

by-language

Keeps the original filename but creates a language directory:

locales/en/i18n.json
→
locales/fr/i18n.json

---

Placeholder Protection

To prevent specific content from being translated, wrap it in:

{{placeholder}}

Anything inside {{}} is preserved.

---

Glossary Support

A glossary file can be provided as a simple JSON key-value mapping.

Example:

{
  "Key": "Value"
}

---

Contributing

Contributions are welcome.

Please:

• Keep code fully type-annotated
• Add docstrings to public functions and classes
• Include tests for business logic
• Follow existing structure and conventions

Refer to the pull request template for contribution guidelines.