{"slug": "rewrite-git-commit-messages-safely-with-git-translate-commits", "title": "Rewrite Git Commit Messages Safely with git-translate-commits", "summary": "An open-source Python CLI called git-translate-commits translates Git commit messages into a target language, defaulting to a local Argos Translate engine that needs no API key. The tool creates a backup branch and skips already-translated messages by default, and its documentation recommends a dry-run preview on a disposable clone before rewriting history, since rewriting changes commit IDs. The v1.0.1 release requires Python 3.10 or later and is licensed under GPL-3.0-or-later.", "body_md": "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.\n\n[`git-translate-commits`](https://github.com/paladini/git-translate-commits) is an open-source Python CLI for translating commit messages to a target language. Its default engine uses [Argos Translate](https://github.com/argosopentech/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.\n\nThe 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.\n\nInstall the release with `pipx`, preview a translation on a disposable clone, and only then run the rewrite on a repository you control:\n\n```\npipx install git-translate-commits\ngit clone https://github.com/example/project.git project-copy\ncd project-copy\ngit-translate-commits --lang en --dry-run\ngit-translate-commits --lang en\n```\n\nThe command creates a backup branch by default before rewriting. Still, treat the operation as history surgery: coordinate with collaborators before force-pushing rewritten refs.\n\nYou need:\n\n`v1.0.1` release declares `requires-python = \">=3.10\"`.` pipx`, `uv`, or `pip` for installation.\nThe project is licensed under [GPL-3.0-or-later](https://github.com/paladini/git-translate-commits/blob/v1.0.1/LICENSE). The release source and metadata are available at the [v1.0.1 tag](https://github.com/paladini/git-translate-commits/tree/v1.0.1).\n\nThe README recommends an isolated CLI installation with `pipx`:\n\n```\npipx install git-translate-commits\n```\n\nYou can use `uv` instead:\n\n```\nuv tool install git-translate-commits\n```\n\nFor development or a one-off environment, plain `pip` is also supported:\n\n```\npython -m pip install git-translate-commits\n```\n\nVerify the installation through the executable and inspect the current options:\n\n```\ngit-translate-commits --version\ngit-translate-commits --help\n```\n\nThe `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.\n\nDo not begin with your only clone. Make a disposable copy, or clone the repository again for the preview:\n\n```\ngit clone https://github.com/your-account/your-project.git history-preview\ncd history-preview\ngit status --short\ngit-translate-commits --lang en --dry-run\n```\n\nThe `--lang` option is required. The repository documents language codes such as `en`, `pt-BR`, `es`, `fr`, `de`, and `ja`. The default engine is local:\n\n```\ngit-translate-commits --lang en --engine local --dry-run\n```\n\nOn 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.\n\nUse the preview to answer three questions before changing anything:\n\nIf the preview is too broad, add filters. For example, process one author or a date range:\n\n```\ngit-translate-commits --lang en --author \"dev@example.com\" --dry-run\ngit-translate-commits --lang en --since \"2025-01-01\" --until \"2025-12-31\" --dry-run\n```\n\nOnce the preview is acceptable, create a separate working clone or confirm that you can restore the original refs. The default rewrite command is:\n\n```\ngit-translate-commits --lang en\n```\n\nThe project documents these default protections:\n\n`--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.`Co-authored-by` and `Signed-off-by` are preserved.`#123` and `JIRA-456` are preserved.\nYou can select branches explicitly instead of processing the current branch:\n\n```\ngit-translate-commits --lang en --branch main\ngit-translate-commits --lang en --branch main --branch release\ngit-translate-commits --lang en --all-branches\n```\n\nDo 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.\n\nA successful command is not enough. Inspect the rewritten history and the generated log:\n\n```\ngit status --short\ngit log --oneline --decorate -n 10\nGet-ChildItem .git-translate-log.json\ngit branch --list\n```\n\nOn 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.\n\nThen compare representative commits against the backup branch. Commit hashes must change when messages change because the message is part of each commit's identity:\n\n```\ngit show backup-before-translation:README.md > $null\ngit log --format=\"%h %s\" backup-before-translation -n 10\ngit log --format=\"%h %s\" HEAD -n 10\n```\n\nThe 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.\n\nThe 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.\n\nThe 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:\n\n```\npipx install \"git-translate-commits[llm]\"\ngit-translate-commits --lang en --engine llm --provider openai --model gpt-4o-mini\n```\n\nThe 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.\n\nThis 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.\n\nThe 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.\n\nThe 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.\n\nThe 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.\n\nNo. The documented purpose is translating Git commit messages. Verify the working tree and representative file hashes if the history is business-critical.\n\nYes. Use `--since` and optionally `--until`, or filter by `--author` and `--branch`.\n\nThe default `--skip-already-translated` behavior is intended for that case. Review the dry-run output because language detection is not perfect.\n\nOnly with agreement from everyone consuming it. A rewritten public branch creates coordination work even when the translated messages are correct.\n\n`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.\n\nHave you standardized mixed-language commit history before, and would you prefer a local translation engine or a reviewed manual rewrite for a shared repository?\n\nAI 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.", "url": "https://wpnews.pro/news/rewrite-git-commit-messages-safely-with-git-translate-commits", "canonical_source": "https://dev.to/paladini/rewrite-git-commit-messages-safely-with-git-translate-commits-55kh", "published_at": "2026-10-26 12:37:00+00:00", "updated_at": "2026-10-26 12:43:20.020926+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools"], "entities": ["git-translate-commits", "Argos Translate", "GitHub", "pipx", "uv"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/rewrite-git-commit-messages-safely-with-git-translate-commits", "markdown": "https://wpnews.pro/news/rewrite-git-commit-messages-safely-with-git-translate-commits.md", "text": "https://wpnews.pro/news/rewrite-git-commit-messages-safely-with-git-translate-commits.txt", "jsonld": "https://wpnews.pro/news/rewrite-git-commit-messages-safely-with-git-translate-commits.jsonld"}}