Rewrite Git Commit Messages Safely with git-translate-commits
---
title: "Rewrite Git Commit Messages Safely with git-translate-commits"
published: true
description: "Translate mixed-language Git commit history locally, preview the rewrite, preserve metadata, and keep a recovery branch before rewriting."
tags: git,python,tutorial,localization
---
Mixed-language commit history is easy to create and hard to search. An AI coding assistant may write one commit in English, another in Portuguese, and a third with a Conventional Commit prefix that you still want to keep. The result is a history that is technically valid but less useful to humans and release tooling.
git-translate-commits is an open-source Python CLI for translating commit messages to a target language. Its default engine uses Argos Translate locally. It also has an optional LLM engine, but this tutorial stays on the local path so the example does not need an API key or a network request to a model provider.
The important part is not the translation command by itself. Rewriting commits changes commit IDs, so a safe workflow needs a preview, a backup, a narrow scope, and a clear recovery plan.
TL;DR
Install the release with pipx, preview a translation on a disposable clone, and only then run the rewrite on a repository you control:
pipx install git-translate-commits
git clone https://github.com/example/project.git project-copy
cd project-copy
git-translate-commits --lang en --dry-run
git-translate-commits --lang en
The command creates a backup branch by default before rewriting. Still, treat the operation as history surgery: coordinate with collaborators before force-pushing rewritten refs.
Prerequisites
You need:
- Python 3.10 or newer. The stable v1.0.1 release declares requires-python = ">=3.10".
- Git and a local clone with a clean working tree.
- pipx, uv, or pip for installation.
- A repository whose history you are allowed to rewrite.
The project is licensed under GPL-3.0-or-later. The release source and metadata are available at the v1.0.1 tag.
Install the stable release
The README recommends an isolated CLI installation with pipx:
pipx install git-translate-commits
You can use uv instead:
uv tool install git-translate-commits
For development or a one-off environment, plain pip is also supported:
python -m pip install git-translate-commits
Verify the installation through the executable and inspect the current options:
git-translate-commits --version
git-translate-commits --help
The v1.0.1 package metadata and the CLI version callback are not currently aligned: the package metadata declares 1.0.1, while the callback reports 1.0.0. That does not change the documented command surface, but it is worth recording when you verify the installation.
Preview a local translation
Do not begin with your only clone. Make a disposable copy, or clone the repository again for the preview:
git clone https://github.com/your-account/your-project.git history-preview
cd history-preview
git status --short
git-translate-commits --lang en --dry-run
The --lang option is required. The repository documents language codes such as en, pt-BR, es, fr, de, and ja. The default engine is local:
git-translate-commits --lang en --engine local --dry-run
On first use, Argos Translate may download language packs, which the project README describes as roughly 50 MB per pack. After the pack is available, the local engine is designed to run without an API key and without sending commit messages to an LLM provider.
Use the preview to answer three questions before changing anything:
1. Does the detected source language match the history you intended to process?
2. Do the proposed translations preserve the meaning of commit messages?
3. Is the repository scope narrow enough for this rewrite?
If the preview is too broad, add filters. For example, process one author or a date range:
git-translate-commits --lang en --author "dev@example.com" --dry-run
git-translate-commits --lang en --since "2025-01-01" --until "2025-12-31" --dry-run
Rewrite with a recovery branch
Once the preview is acceptable, create a separate working clone or confirm that you can restore the original refs. The default rewrite command is:
git-translate-commits --lang en
The project documents these default protections:
- --backup is enabled, so a backup branch is created before changes.
- --skip-already-translated is enabled, so messages already detected in the target language can be skipped.
- --preserve-conventional is enabled, so prefixes such as feat:, fix:, and chore: are preserved.
- Git trailers such as Co-authored-by and Signed-off-by are preserved.
- Issue references such as #123 and JIRA-456 are preserved.
You can select branches explicitly instead of processing the current branch:
git-translate-commits --lang en --branch main
git-translate-commits --lang en --branch main --branch release
git-translate-commits --lang en --all-branches
Do not add --force until you understand the confirmation step. The flag skips confirmation, which is useful for automation but removes an intentional pause before a destructive history rewrite.
Verify the result
A successful command is not enough. Inspect the rewritten history and the generated log:
git status --short
git log --oneline --decorate -n 10
Get-ChildItem .git-translate-log.json
git branch --list
On Unix-like shells, the final command can be replaced with ls -l .git-translate-log.json. The project documents .git-translate-log.json as the JSON operation log containing the mapping of changes.
Then compare representative commits against the backup branch. Commit hashes must change when messages change because the message is part of each commit's identity:
git show backup-before-translation:README.md > $null
git log --format="%h %s" backup-before-translation -n 10
git log --format="%h %s" HEAD -n 10
The exact backup branch name is reported by the tool, so replace backup-before-translation with the name shown in your run. Check authors, timestamps, trailers, issue references, and file contents. The intended change is the commit message, not the tree.
Why the local path is useful
The local engine separates the basic workflow from provider credentials. That makes a dry run easier to reproduce and keeps ordinary commit text on the local machine after language packs are installed. It also makes the trade-off explicit: local neural translation may be less context-aware than an LLM translation, especially for project-specific terminology.
The optional LLM engine is a separate path. Install the extra dependency and configure a provider only when you have accepted the data handling and cost implications:
pipx install "git-translate-commits[llm]"
git-translate-commits --lang en --engine llm --provider openai --model gpt-4o-mini
The repository documents OpenAI, Anthropic, and OpenAI-compatible providers. It also recommends environment variables such as OPENAI_API_KEY and ANTHROPIC_API_KEY. Never put a real key in a commit message, shell history that you intend to share, or an article example.
Failure modes and limits
Commit IDs change
This is expected. A rewritten commit is a different object, so existing remote branches, pull requests, tags, and clones do not automatically follow it. Coordinate the force-push and ask collaborators to re-clone or carefully reset their local refs.
Translation quality is not guaranteed
The tool preserves selected structure, not intent. Review translations containing product names, legal terms, incident details, or specialized abbreviations. A preserved Conventional Commit prefix does not prove that the rest of the message is accurate.
Backups are local recovery aids
The automatic backup branch helps you recover from a local mistake. It is not a substitute for a verified remote backup, a release tag, or a team communication plan. Do not assume that a backup branch was pushed unless you explicitly verify it.
LLM mode changes the trust boundary
The local engine and the LLM engine are not equivalent. LLM mode can send commit text to the configured provider and can incur provider charges. Use the local mode for sensitive history unless your organization's policy allows the external provider path.
FAQ
Does this translate file contents?
No. The documented purpose is translating Git commit messages. Verify the working tree and representative file hashes if the history is business-critical.
Can I translate only recent commits?
Yes. Use --since and optionally --until, or filter by --author and --branch.
Can I avoid changing already English messages?
The default --skip-already-translated behavior is intended for that case. Review the dry-run output because language detection is not perfect.
Should I rewrite a shared public branch?
Only with agreement from everyone consuming it. A rewritten public branch creates coordination work even when the translated messages are correct.
Takeaway
git-translate-commits is most useful when treated as a controlled migration: preview on a disposable clone, use the local engine when privacy matters, keep the automatic backup, verify the log and commit metadata, and coordinate before updating shared refs. The translation is the easy part. The recovery and communication plan are what make the rewrite safe.
Have you standardized mixed-language commit history before, and would you prefer a local translation engine or a reviewed manual rewrite for a shared repository?
AI assistance disclosure
AI assistance was used to organize this tutorial and edit its prose. The repository documentation, stable release metadata, license, source behavior, and local test results were checked separately. The article does not claim that the AI ran a production history rewrite.
Mentions
Argos Translate - open-source offline machine translation. Runs fully local, no data leaves your machine, no limits, no subscription. 40+ languages via OpenNMT + CTranslate2. MIT/CC0. LibreTranslate is the web/API layer on top. argosopentech/argos-translate
Rewrite Git Commit Messages Safely with git-translate-commits --- title: "Rewrite Git Commit Messages Safely with git-translate-commits" published: true description: "Translate mixed-language Git commit history locally, preview the rewrite, preserve metadata, and keep a recovery branch before rewriting." tags: git,python,tutorial,localization --- Mixed-language commit history is easy to create and hard to search. An AI coding assistant may write one commit in English, another in Portuguese, and a third with a Conventional Commit prefix that you still want to keep. The result is a history that is technically valid but less useful to humans and release tooling. git-translate-commits is an open-source Python CLI for translating commit messages to a target language. Its default engine uses Argos Translate locally. It also has an optional LLM engine, but this tutorial stays on the local path so the example does not need an API key or a network request to a model provider. The important part is not the translation command by itself. Rewriting commits changes commit IDs, so a safe workflow needs a preview, a backup, a narrow scope, and a clear recovery plan. TL;DR Install the release with pipx, preview a translation on a disposable clone, and only then run the rewrite on a repository you control: pipx install git-translate-commits git clone https://github.com/example/project.git project-copy cd project-copy git-translate-commits --lang en --dry-run git-translate-commits --lang en The command creates a backup branch by default before rewriting. Still, treat the operation as history surgery: coordinate with collaborators before force-pushing rewritten refs. Prerequisites You need: - Python 3.10 or newer. The stable v1.0.1 release declares requires-python = ">=3.10". - Git and a local clone with a clean working tree. - pipx, uv, or pip for installation. - A repository whose history you are allowed to rewrite. The project is licensed under GPL-3.0-or-later. The release source and metadata are available at the v1.0.1 tag. Install the stable release The README recommends an isolated CLI installation with pipx: pipx install git-translate-commits You can use uv instead: uv tool install git-translate-commits For development or a one-off environment, plain pip is also supported: python -m pip install git-translate-commits Verify the installation through the executable and inspect the current options: git-translate-commits --version git-translate-commits --help The v1.0.1 package metadata and the CLI version callback are not currently aligned: the package metadata declares 1.0.1, while the callback reports 1.0.0. That does not change the documented command surface, but it is worth recording when you verify the installation. Preview a local translation Do not begin with your only clone. Make a disposable copy, or clone the repository again for the preview: git clone https://github.com/your-account/your-project.git history-preview cd history-preview git status --short git-translate-commits --lang en --dry-run The --lang option is required. The repository documents language codes such as en, pt-BR, es, fr, de, and ja. The default engine is local: git-translate-commits --lang en --engine local --dry-run On first use, Argos Translate may download language packs, which the project README describes as roughly 50 MB per pack. After the pack is available, the local engine is designed to run without an API key and without sending commit messages to an LLM provider. Use the preview to answer three questions before changing anything: 1. Does the detected source language match the history you intended to process? 2. Do the proposed translations preserve the meaning of commit messages? 3. Is the repository scope narrow enough for this rewrite? If the preview is too broad, add filters. For example, process one author or a date range: git-translate-commits --lang en --author "dev@example.com" --dry-run git-translate-commits --lang en --since "2025-01-01" --until "2025-12-31" --dry-run Rewrite with a recovery branch Once the preview is acceptable, create a separate working clone or confirm that you can restore the original refs. The default rewrite command is: git-translate-commits --lang en The project documents these default protections: - --backup is enabled, so a backup branch is created before changes. - --skip-already-translated is enabled, so messages already detected in the target language can be skipped. - --preserve-conventional is enabled, so prefixes such as feat:, fix:, and chore: are preserved. - Git trailers such as Co-authored-by and Signed-off-by are preserved. - Issue references such as #123 and JIRA-456 are preserved. You can select branches explicitly instead of processing the current branch: git-translate-commits --lang en --branch main git-translate-commits --lang en --branch main --branch release git-translate-commits --lang en --all-branches Do not add --force until you understand the confirmation step. The flag skips confirmation, which is useful for automation but removes an intentional pause before a destructive history rewrite. Verify the result A successful command is not enough. Inspect the rewritten history and the generated log: git status --short git log --oneline --decorate -n 10 Get-ChildItem .git-translate-log.json git branch --list On Unix-like shells, the final command can be replaced with ls -l .git-translate-log.json. The project documents .git-translate-log.json as the JSON operation log containing the mapping of changes. Then compare representative commits against the backup branch. Commit hashes must change when messages change because the message is part of each commit's identity: git show backup-before-translation:README.md > $null git log --format="%h %s" backup-before-translation -n 10 git log --format="%h %s" HEAD -n 10 The exact backup branch name is reported by the tool, so replace backup-before-translation with the name shown in your run. Check authors, timestamps, trailers, issue references, and file contents. The intended change is the commit message, not the tree. Why the local path is useful The local engine separates the basic workflow from provider credentials. That makes a dry run easier to reproduce and keeps ordinary commit text on the local machine after language packs are installed. It also makes the trade-off explicit: local neural translation may be less context-aware than an LLM translation, especially for project-specific terminology. The optional LLM engine is a separate path. Install the extra dependency and configure a provider only when you have accepted the data handling and cost implications: pipx install "git-translate-commits[llm]" git-translate-commits --lang en --engine llm --provider openai --model gpt-4o-mini The repository documents OpenAI, Anthropic, and OpenAI-compatible providers. It also recommends environment variables such as OPENAI_API_KEY and ANTHROPIC_API_KEY. Never put a real key in a commit message, shell history that you intend to share, or an article example. Failure modes and limits Commit IDs change This is expected. A rewritten commit is a different object, so existing remote branches, pull requests, tags, and clones do not automatically follow it. Coordinate the force-push and ask collaborators to re-clone or carefully reset their local refs. Translation quality is not guaranteed The tool preserves selected structure, not intent. Review translations containing product names, legal terms, incident details, or specialized abbreviations. A preserved Conventional Commit prefix does not prove that the rest of the message is accurate. Backups are local recovery aids The automatic backup branch helps you recover from a local mistake. It is not a substitute for a verified remote backup, a release tag, or a team communication plan. Do not assume that a backup branch was pushed unless you explicitly verify it. LLM mode changes the trust boundary The local engine and the LLM engine are not equivalent. LLM mode can send commit text to the configured provider and can incur provider charges. Use the local mode for sensitive history unless your organization's policy allows the external provider path. FAQ Does this translate file contents? No. The documented purpose is translating Git commit messages. Verify the working tree and representative file hashes if the history is business-critical. Can I translate only recent commits? Yes. Use --since and optionally --until, or filter by --author and --branch. Can I avoid changing already English messages? The default --skip-already-translated behavior is intended for that case. Review the dry-run output because language detection is not perfect. Should I rewrite a shared public branch? Only with agreement from everyone consuming it. A rewritten public branch creates coordination work even when the translated messages are correct. Takeaway git-translate-commits is most useful when treated as a controlled migration: preview on a disposable clone, use the local engine when privacy matters, keep the automatic backup, verify the log and commit metadata, and coordinate before updating shared refs. The translation is the easy part. The recovery and communication plan are what make the rewrite safe. Have you standardized mixed-language commit history before, and would you prefer a local translation engine or a reviewed manual rewrite for a shared repository? AI assistance disclosure AI assistance was used to organize this tutorial and edit its prose. The repository documentation, stable release metadata, license, source behavior, and local test results were checked separately. The article does not claim that the AI ran a production history rewrite.
😤 出国前才想起来，翻译软件断网就废了！argos-translate 把模型下到本地，离线也能翻几十种语言，文档整篇丢进去。6500 星，不注册不登录。 argosopentech/argos-translate
Ерөнхийдөө анхных буюу Argotrain-д (argosopentech/argos-train) Хангалттай чанартай хийх анхны алхам ба кодчилоход Хагас жил зарцуулсан бол одоо харин NLLB-200-distilled-600M-д Ердөө л 2 сар (дундуур нь ажил,амралт ба аялал этр) зарцууллаа😁🤓 Одоо Qwen 2.5 3B, 7B, 14B ба 70B гээд Гялс гялс дуусгачихаад дүрэм ярианы сайжруулалтандаа анхаараад анхны ашиглалтаа Амьдаар нь 1 сард харуулж магадгүй, үгүй ч байж магадгүй😁😅😂😂 Сайн дурын уран сайхан ч шөө🤗