My pre-commit hook passed a broken commit

Mohamed Almearag — Sat, 24 Oct 2026 08:51:09 +0000

Locale Guard is my GitHub Action and CLI for translation files. It catches missing keys, broken placeholders, plural forms and untranslated text on pull requests, and since version 1.3.0 (npx locale-guard-cli) before each commit too. It's listed in the i18next docs and the awesome-i18n list.

The first version of its pre-commit hook let a broken commit through. Here's what went wrong and what I changed.

A pre-commit hook must check what the commit holds

My first hook ran the CLI on the files on disk. Then I tried this:

Add a key to en.json and git add it.
Translate it in ar.json, de.json and fr.json, but forget to git add them.
Commit.

The hook passed. The files on disk were complete, so the check was happy. But the commit held only the English key, and the other languages were missing it.

A pre-commit hook has to read the staged files, not the working tree. Now --staged reads them from git: git ls-files --stage lists each staged file with the id of its content, and one git cat-file --batch process reads them all. With that, the same commit stops:

messages/ar.json
  2:3  error    Missing key Nav.deals  missing-keys

messages/de.json
  2:3  error    Missing key Nav.deals  missing-keys

messages/fr.json
  2:3  error    Missing key Nav.deals  missing-keys

✖ 3 new issues (3 errors) since the last commit
  2 existing issues are not shown. --all lists every issue.
husky - pre-commit script failed (code 1)

Hooks can be skipped with --no-verify, so there is also a pre-push hook that compares the branch with origin/main, and the check on the pull request stays on.

Try it

npx locale-guard-cli --all --files "locales/{locale}.json" --format vue-i18n

There are two demos you can clone and break, with Husky and Lefthook, and step-by-step guides.

If it reports something that isn't a bug, please open an issue.

I wrote this post with help from an AI assistant, and checked every detail against the code and the test runs.

The translation bugs code review keeps missing

Mohamed Almearag — Sun, 18 Oct 2026 11:14:08 +0000

In Dashy's Hindi translation, someone translated a variable name. The message said {थीम} instead of {theme}.

The JSON was valid and the diff looked fine. But vue-i18n could not compile the message. In Hindi, clicking Save in the theme editor stored the colors and then threw an error, so no confirmation appeared and the editor stayed open.

I found the same kind of bug in two other projects:

Open WebUI: placeholder names translated in 10 locales.
listmonk: five Arabic messages lost their {name}. Deleting a campaign said only "deleted", without the campaign name.

All three fixes were merged by the maintainers within a day.

Why review misses them

The reviewer usually can't read Hindi or Arabic. The file is valid JSON, so nothing fails. The bug shows up only when a user opens that screen in that language.

Plural forms are worse. Arabic has six of them: zero, one, two, few, many and other. Most projects write two, because English has two.

What I built

Locale Guard is a GitHub Action that runs on every pull request. It reads the locale files with each library's own message parser, compares every language with the base one, and writes one comment with:

missing keys, with a block ready to paste into each file
placeholders, ICU arguments and tags that differ from the base message
messages that don't compile
plural forms each language needs, from Intl.PluralRules
text that was never translated

It works with vue-i18n (and Nuxt), next-intl, react-intl, i18next and Rails locale files.

Old projects

Most projects already have hundreds of these issues, so a check that fails on all of them gets turned off in a week.

Locale Guard runs the same checks on the base branch and fails only on what the pull request adds. Old issues are counted and collapsed. On Directus, with 70 languages and about 104,000 existing issues, a pull request is still judged only on what it changes.

Setup

name: Translations

on: pull_request

permissions:
  contents: read
  pull-requests: write

jobs:
  locale-guard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: Mohamed-Almarag/locale-guard@v1
        with:
          files: locales/{locale}.json
          format: vue-i18n

If you try it and it reports something that isn't a bug, please open an issue. False positives are the first thing I want to fix.

I wrote this post with help from an AI assistant, and checked every detail against the merged pull requests.

DEV Community: Mohamed Almearag