{"id":37944953,"url":"https://github.com/lingualdev/i18n-check","last_synced_at":"2026-03-15T01:30:42.209Z","repository":{"id":243750218,"uuid":"812334454","full_name":"lingualdev/i18n-check","owner":"lingualdev","description":"Validate i18n translation files","archived":false,"fork":false,"pushed_at":"2026-02-15T18:02:54.000Z","size":5324,"stargazers_count":165,"open_issues_count":9,"forks_count":8,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-02-16T00:42:04.771Z","etag":null,"topics":["i18n","i18next","react-intl"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lingualdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-06-08T15:40:56.000Z","updated_at":"2026-02-02T12:21:35.000Z","dependencies_parsed_at":"2026-01-16T19:04:32.393Z","dependency_job_id":null,"html_url":"https://github.com/lingualdev/i18n-check","commit_stats":null,"previous_names":["lingualdev/i18n-check"],"tags_count":45,"template":false,"template_full_name":null,"purl":"pkg:github/lingualdev/i18n-check","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lingualdev%2Fi18n-check","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lingualdev%2Fi18n-check/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lingualdev%2Fi18n-check/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lingualdev%2Fi18n-check/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lingualdev","download_url":"https://codeload.github.com/lingualdev/i18n-check/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lingualdev%2Fi18n-check/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30219221,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T14:02:48.375Z","status":"ssl_error","status_checked_at":"2026-03-07T14:02:43.192Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["i18n","i18next","react-intl"],"created_at":"2026-01-16T17:49:11.116Z","updated_at":"2026-03-07T15:00:57.185Z","avatar_url":"https://github.com/lingualdev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lingual i18n-check\n\n**i18n-check** validates your [ICU](https://github.com/unicode-org/icu) and [i18next](https://www.i18next.com/) translation files and checks for missing and broken translations.\nIt compares the defined source language with all target translation files and finds inconsistencies between source and target files.\nYou can run these checks as a pre-commit hook or on the CI depending on your use-case and setup.\n\n![example 1](./assets/i18n_check_multipleFilesFolderExample_basic_v2.png)\n\n![example 2](./assets/i18n_check_multipleFilesFolderExample_react_intl_unused_v2.png)\n\n## Table of Contents\n\n- [Installation](#installation)\n- [General Usage](#general-usage)\n- [CLI Options](#options)\n- [Examples](#examples)\n  - [Single folder](#single-folder)\n  - [Folder per locale](#folder-per-locale)\n  - [Folder per locale with multiple files](#folder-per-locale-with-multiple-files)\n- [Github Action](#as-github-action)\n- [API](#api)\n- [Development](#development)\n- [Links](#links)\n\n## Installation\n\nUsing **yarn**:\n\n```bash\nyarn add --dev @lingual/i18n-check\n```\n\nUsing **npm**:\n\n```bash\nnpm install --save-dev @lingual/i18n-check\n```\n\nUsing **pnpm**:\n\n```bash\npnpm add --save-dev @lingual/i18n-check\n```\n\nAfter the installation, i18n-check can either be accessed via defining a command in the `package.json` file or directly in the CLI.\n\nUpdate your `package.json` and add a new command:\n\n```bash\n\"scripts\": {\n    // ...other commands,\n    \"i18n:check\": \"i18n-check\"\n}\n```\n\nNow you can run the `i18n:check` command directly from the command-line, i.e. `yarn i18n:check`.\n\nAlternatively you can also access the library directly:\n\n```bash\nnode_modules/.bin/i18n-check\n```\n\n## General Usage\n\nFor i18n-check to work you need to provide it at a minimum the source locale (`--source, -s`) for the primary language and the path to the locale translation files (`--locales, -l`). Currently supported file formats are JSON and YAML.\n\nExample:\n\n```bash\nyarn i18n:check -s en-US --locales translations/\n```\n\nInstead of a single source file you can also pass a directory:\n\n```bash\nyarn i18n:check -s en-US --locales translations/\n```\n\nSee the [examples](#examples) for more details.\n\n## Options\n\n### --locales, -l\n\nWith the `-l` or `--locales` option you define which folder or multiple folders you want to run the i18n checks against. It is a **required** option. i18n-check will try to find all target locale files and compare these files against the defined source file(s).\nCheck the [example](#examples) to see how different locale translation files are organised and how they can be addressed.\n\n```bash\nyarn i18n:check --locales translations/messageExamples -s en-US\n```\n\n### --source, -s\n\nWith the `-s` or `--source` option you define the source locale to compare all target files against. It is a **required** option. i18n-check will try to find all target locale files and compare these files against the applicable source file(s).\nCheck the [examples](#examples) to see how different locale translation files are organised and how they can be addressed.\n\n```bash\nyarn i18n:check --locales translations/messageExamples -s en-US\n```\n\n### --format, -f\n\nBy default i18n-check will validate against any [ICU](https://github.com/unicode-org/icu) compliant translations.\nAdditionally the `i18next` format is supported and can be set via the `-f` or `--format` option.\n\nThere are i18n libraries that have their own specific format, which might not be based on ICU and therefore can not be validated against currently. On a side-note: there might be future support for more specific formats.\n\nHint: If you want to use the `--unused` flag, you should provide `react-intl` or `i18-next` as the format. Also see the [`unused` section](#--unused--u) for more details.\n\n```bash\nyarn i18n:check --locales translations/i18NextMessageExamples -s en-US -f i18next\n```\n\n### --only, -o\n\nBy default i18n-check will perform a validation against any **missing** and/or **invalid** keys, additionally **unused** and **undefined** checks if the `--unused` option is set. There are situations where only a specific check should run. By using the `-o` or `--only` option you can specify a specific check to run.\n\nThe available options are:\n\n- `missingKeys`: will check against any missing keys in the target files.\n- `invalidKeys`: will check for invalid keys, where the target translations has a different type then the one defined in the source file.\n- `unused`: will check for any locale keys that do not exist in the codebase.\n- `undefined`: will check for any keys that exist in the codebase but not in the source locale files.\n\nCheck for missing keys only:\n\n```bash\nyarn i18n:check --locales translations/messageExamples -s en-US -o missingKeys\n```\n\nCheck for invalid keys only:\n\n```bash\nyarn i18n:check --locales translations/messageExamples -s en-US -o invalidKeys\n```\n\nCheck for unused key only:\n\n```bash\nyarn i18n:check --locales translations/messageExamples -s en-US -o unused\n```\n\nCheck for undefined keys only:\n\n```bash\nyarn i18n:check --locales translations/messageExamples -s en-US -o undefined\n```\n\nCheck for missing and invalid keys (which is the default):\n\n```bash\nyarn i18n:check --locales translations/messageExamples -s en-US -o missingKeys invalidKeys\n```\n\nCheck for unused and undefined keys only:\n\n```bash\nyarn i18n:check --locales translations/messageExamples -s en-US -o unused undefined\n```\n\n### --unused, -u\n\nThis feature is currently only supported for `react-intl` and `i18next` as well as `next-intl` (experimental at the moment) based React applications and is useful when you need to know which keys exist in your translation files but not in your codebase. Additionally an inverse check is run to find any keys that exist in the codebase but not in the translation files.\n\nVia the `-u` or `--unused` option you provide a source path to the code, which will be parsed to find all unused as well as undefined keys in the primary target language.\n\nIt is important to note that you must also provide the `-f` or `--format` option with `react-intl`, `i18next` or `next-intl` as value. See the [`format` section](#--format--f) for more information.\n\n```bash\nyarn i18n:check --locales translations/messageExamples -s en-US -u client/ -f react-intl\n```\n\nor\n\n```bash\nyarn i18n:check --locales translations/messageExamples -s en-US -u client/ -f i18next\n```\n\nor\n\n```bash\nyarn i18n:check --locales translations/messageExamples -s en-US -u client/ -f next-intl\n```\n\n### --reporter, -r\n\nThe standard reporting prints out all the missing or invalid keys.\nUsing the `-r` or `--reporter` option enables to override the standard error reporting. Passing the `summary` option will print a summary of the missing or invalid keys.\n\n```bash\nyarn i18n:check --locales translations/messageExamples -s en-US -r summary\n```\n\n### --exclude, -e\n\nThere are situations where we want to exclude a single or multiple files or a single folder or a group of folders. A typical scenario would be that some keys are missing in a specific folder, as they are being work in progress for example. To exclude this or these files/folders you can use the `-e` or `--exclude` option. It expects one or more files and/or folders.\n\nTo exclude a single file:\n\n```bash\nyarn i18n:check --locales translations/messageExamples -s en-US -e translations/messageExamples/fr-fr.json\n```\n\nTo exclude multiple files provide all files:\n\n```bash\nyarn i18n:check --locales translations/messageExamples -s en-US -e translations/messageExamples/fr-fr.json translations/messageExamples/de-at.json\n```\n\nTo exclude a single folder:\n\n```bash\nyarn i18n:check --locales translations/folderExamples -s en-US -e translations/folderExamples/fr/*\n```\n\nAlternatively you can exclude multiple folders by providing the folders to be excluded:\n\n```bash\nyarn i18n:check --locales translations/folderExamples -s en-US -e translations/folderExamples/fr/* translations/folderExample/it/*\n```\n\nThe `--exclude` option also accepts a mix of files and folders, which follows the same pattern as above, i.e.\n`-e translations/folderExamples/fr/* translations/messageExamples/it.json`\n\n### --ignore, -i\n\nThere can be situations where we only want to translate a feature for a specific region and therefore need to ignore any missing key checks against non supported locales. Another scenario is that we know of the missing keys and want to be able to skip these missing keys when running checks. For these aforementioned scenarios, by using the `--ignore` or `-i` option you can specify which keys to ignore, additionally also being able to define ignoring all keys inside a defined path, i.e. `some.keys.path.*`.\n\nTo ignore regular keys:\n\n```bash\nyarn i18n:check --locales translations/folderExamples -s en-US -i some.key.to.ignore other.key.to.ignore\n```\n\nTo ignore all keys within a provided path:\n\n```bash\nyarn i18n:check --locales translations/folderExamples -s en-US -i \"some.path.to.keys.*\"\n```\n\nA mix of regular keys and paths:\n\n```bash\nyarn i18n:check --locales translations/folderExamples -s en-US -i \"some.path.to.keys.*\" some.key.to.ignore other.key.to.ignore\n```\n\n### --parser-component-functions\n\nWhen using the `--unused` option, there will be situations where the i18next-parser will not be able to find components that wrap a `Trans` component. The component names for i18next-parser to match should be provided via the `--parser-component-functions` option. This option should only be used to define additional names for matching, as by default `Trans` will always be matched.\n\n```bash\nyarn i18n:check --locales translations/i18NextMessageExamples -s en-US -f i18next\n-u src --parser-component-functions WrappedTransComponent\n```\n\n```bash\nyarn i18n:check --locales translations/i18NextMessageExamples -s en-US -f i18next\n-u src --parser-component-functions WrappedTransComponent AnotherWrappedTransComponent\n```\n\n## Examples\n\ni18n-check is able to load and validate against different locale folder structures. Depending on how the locale files are organized, there are different configuration options.\n\n### Single folder\n\nIf all the locales are organized in a **single folder**:\n\n```\nlocales/\n  en-en.json\n  de-de.json\n```\n\nUse the `-l` or `--locales` option to define the directory that should be checked for target files. With the `s` or `source` option you can specify the base/reference file to compare the target files against.\n\n```bash\nyarn i18n:check --locales locales -s locales/en-us.json\n```\n\n### Folder per locale\n\nIf the locales are **organised as folders** containing a single JSON/YAML file:\n\n```\nlocales/\n  en-US/\n    index.json\n  de-DE/\n    index.json\n```\n\nDefine the `locales` folder as the directory to look for target files.\n\n```bash\nyarn i18n:check --locales locales -s en-US\n```\n\n### Folder per locale with multiple files\n\nIf the locales are **organised as folders** containing multiple JSON/YAML files:\n\n```\nlocales/\n  en-US/\n    one.json\n    two.json\n    three.json\n  de-DE/\n    one.json\n    two.json\n    three.json\n```\n\nDefine the `locales` folder as the directory to look for target files and pass `locales/en-US/` as the `source` option. i18n-check will try to collect all the files in the provided source directory and compare each one against the corresponding files in the target locales.\n\n```bash\nyarn i18n:check --locales locales -s en-US\n```\n\n#### Multiple folders containing locales\n\nIf the locales are **organised as folders** containing multiple JSON/YAML files:\n\n```\n- spaceOne\n  - locales/\n    - en-US/\n      - one.json\n      - two.json\n      - three.json\n    - de-DE/\n      - one.json\n      - two.json\n      - three.json\n- spaceTwo\n  - locales/\n    - en-US/\n      - one.json\n      - two.json\n      - three.json\n    - de-DE/\n      - one.json\n      - two.json\n      - three.json\n```\n\nDefine the `locales` folder as the directory to look for target files and pass `en-US` as the `source` option. i18n-check will try to collect all the files in the provided source directory and compare each one against the corresponding files in the target locales.\n\n```bash\nyarn i18n:check -l spaceOne spaceTwo -s en-US\n```\n\n## As Github Action\n\nWe currently do not offer an explicit **Github Action** you can use out of the box, but if you have i18n-check already installed, you can define your own **YAML** file. The following example can be seen as a starting point that you can adapt to your current setup:\n\n```yml\nname: i18n Check\non:\n  pull_request:\n    branches:\n      - main\n  push:\n    branches:\n      - main\n\njobs:\n  i18n-check:\n    runs-on: ubuntu-latest\n\n    steps:\n      - uses: actions/checkout@master\n\n      - name: yarn install \u0026 build\n        run: |\n          yarn install\n          yarn build\n\n      - name: yarn i18n-check\n        run: |\n          yarn i18n-check --locales translations/messageExamples --source en-US\n```\n\nThe above workflow will return any missing or invalid keys and the action would fail if missing/invalid keys are found:\n\n![i18n-check Github workflow example out](./assets/i18n-check-workflow-example.png)\n\n## API\n\nAside from using the CLI, i18n-check also exposes a set of check functions that can be accessed programmatically.\nStart by importing i18n-check:\n\n```ts\nimport * as i18nCheck from '@lingual/i18n-check';\n```\n\n### `i18nCheck.checkTranslations(source, targets [, options])`\n\n`checkTranslations` expects the base and comparison or target files and returns an object containing the missing and invalid keys. The optional `options` objects can be provided as a third argument to define the format style via the `format` property, this is useful if you want to validate `i18next` specific translations.\n\n```ts\nimport { checkTranslations } from '@lingual/i18n-check';\n\nconst options = {\n  format: 'i18next',\n};\n\nconst { invalidKeys, missingKeys } = checkTranslations(\n  source,\n  targets,\n  options\n);\n```\n\nAdditionally the `options` object enables to also define which checks should run via the `checks` property, f.e. if you only want to check for missing or invalid keys only.\n\n```ts\nimport { checkTranslations } from '@lingual/i18n-check';\n\nconst options = {\n  format: 'icu',\n  checks: ['invalidKeys'],\n};\n\nconst { invalidKeys } = checkTranslations(source, targets, options);\n```\n\nCalling `checkTranslation` will return the following shape:\n\n```ts\nexport type CheckResult = Record\u003cstring, string[]\u003e;\n\ntype Result = {\n  missingKeys: CheckResult | undefined;\n  invalidKeys: CheckResult | undefined;\n};\n```\n\nThe result for `missingKeys` as well as `invalidKeys` is an object containing the provided locales and their corresponding affected keys as an array\n\n```ts\n{\n  missingKeys:\n    {\n        \"de-de\": [\"missing_example_key\", \"some_other_key\"],\n        \"fr-fr\": [],\n    }\n};\n```\n\n### `i18nCheck.checkMissingTranslations(source, targets)`\n\n`checkMissingTranslations` checks for any missing keys in the target files. All files are compared against the source file.\n\n```ts\nimport { checkMissingTranslations } from '@lingual/i18n-check';\n\nconst result = checkMissingTranslations(source, targets);\n\n// {\n//  \"de-de\": [\"missing_translation_key\", \"some_other_missing_translation_key\"],\n//  \"fr-fr\": [],\n// };\n```\n\nThe result is an object containing the provided locales and their corresponding missing keys as an array.\n\n### `i18nCheck.checkInvalidTranslations(source, targets [, options])`\n\n`checkInvalidTranslations` checks if there are any invalid keys in the target files. All files are compared against the source file.\n\n```ts\nimport { checkInvalidTranslations } from '@lingual/i18n-check';\n\nconst options = {\n  format: 'i18next',\n};\n\nconst result = checkInvalidTranslations(source, targets, options);\n\n// {\n//  \"de-de\": [\"invalid_translation_key\", \"some_other_invalid_translation_key\"],\n//  \"fr-fr\": [],\n// };\n```\n\nThe result is an object containing the provided locales and their corresponding invalid keys as an array.\n\n## Development\n\nIf you want to checkout and run the code, you need to run the `build` command first.\n\nRun `pnpm run build` and then depending on the scenario one of the following commands.\n\nBasic icu translation example:\n\n```bash\nnode dist/bin/index.js --locales translations/messageExamples -s en-US\n```\n\nFlatted translation keys example:\n\n```bash\nnode dist/bin/index.js --locales translations/flattenExamples -s en-US\n```\n\ni18next translation example:\n\n```bash\nnode dist/bin/index.js --locales translations/i18NextMessageExamples -s en-US -f i18next\n```\n\nSingle file translation example:\n\n```bash\nnode dist/bin/index.js --locales translations/folderExample -s en-US\n```\n\nMultiple files per folder translation example:\n\n```bash\nnode dist/bin/index.js --locales translations/multipleFilesFolderExample/ -s en-US\n```\n\nMultiple folders containing locales translation example:\n\n```bash\nnode dist/bin/index.js --locales translations/folderExample,translations/messageExamples -s en-US\n```\n\n### Tests\n\nTo run the tests use one of the following commands:\n\n```bash\npnpm test\n```\n\n## Links\n\n- [Introducing i18n-check](https://lingual.dev/blog/introducing-i18n-check/)\n- [Twitter](https://twitter.com/lingualdev)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flingualdev%2Fi18n-check","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flingualdev%2Fi18n-check","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flingualdev%2Fi18n-check/lists"}