# Validate your translations and other files with file-json-validator # TL: DR npm package `file-json-validator` to validate file structure and `json` keys: * [https://www.npmjs.com/package/file-json-validator](https://www.npmjs.com/package/file-json-validator) * [https://github.com/Isur/file-json-validator](https://github.com/Isur/file-json-validator) Example use case - check if your translations have the same files/keys for each language. # Context A web application that you and your team are creating is growing and you are adding new languages. Some tools and packages will help you manage that in your app. Often you will have some `json` files that will contain all your translations. It might be something like this: ```bash ./public └── locales ├── en │   ├── buttons.json │   └── common.json ├── ger │   ├── buttons.json │   └── common.json └── pl └── common.json ``` Sometimes it might be a little problematic. # Problem As you can see in the example file structure above, one `json` file is missing. In this simple example, this is not an issue; it's easy to find and easy to fix. However, consider a larger codebase with more files, or larger files containing numerous keys, possibly even nested keys. It's easy to forget to add a key to one of the `json` files or make a typo. If you don't check all translations, you might not notice that something is missing - your texts could be missing or falling back to another language. This is something that happened in some of the projects I was involved in. We had to look through files to find what is wrong. So I thought about a solution that will help us. # Solution How can you avoid issues with missing keys and files, especially when dealing with a lot of translations? This is where I came up with an idea that something like a linter would be a good addition to the CI. When someone modifies translations and pushes the code to our repository with GitHub actions enabled, it will automatically verify everything. To achieve this, I developed a CLI tool to handle the task. The package and its source code can be found here: * https://www.npmjs.com/package/file-json-validator * https://github.com/Isur/file-json-validator # Usage ## Installation To use it in the project install it as (dev) dependency and use `fjv` as a CLI tool. ```bash pnpm add file-json-validator ``` ## CLI commands There are a few commands that you can use depending on what you want to check: | Command | Description | | --- | --- | | `fjv compare` | Compare the content of directories inside the selected directory. | | `fjv dir` | Compare selected directories. | | `fjv json` | Compare selected `json` files. | ## Examples If your file structure is like this: ```bash ./public └── locales ├── en │   ├── buttons.json │   └── common.json ├── ger │   ├── buttons.json │   └── common.json └── pl └── common.json ``` Then you can use CLI: ```bash fjv compare ./public/locales en ``` The first argument is the command `compare`, second is pointing at the directory containing all other language directories and the last argument is the default language that others will be compared with. Example output for this command will be like: ```bash Directory structure: (1 errors) ./public/locales/pl -buttons.json ./public/locales/ger ==> OK Json content: (3 errors) ./public/locales/ger/buttons.json ==> OK ./public/locales/pl/common.json ==> OK ./public/locales/ger/common.json -calc.minus -calc.equal +no ``` It shows files that are correct and highlights any differences that shouldn't exist. If there is a `-`, it means something is missing. If there is a `+`, it means there is something extra that shouldn't be there. If there are any differences, it will exit with an error - which is useful in GitHub actions. Similar behavior with the second command: `dir`. ```bash fjv dir ./public/locales/en ./public/locales/pl ./public/locales/ger ``` The first argument is the main language and the rest are other selected languages. The result is in the same format as for `compare` command. The last one is `json` where the arguments are just `json` files. ```bash fjv json ./public/locales/en/common.json ./public/locales/pl/common.json ./public/locales/ger/common.json ``` Where again, the first one is the main, the rest are compared to it. ## Flags For all commands, there are available some flags to add: | Flag | Description | Command | | --- | --- | --- | | `--only-warn` | Do not exit with an error if there are any diffs. | `compare`, `dir`, `json` | | `--show-only-errors` | Show only errors. | `compare`, `dir`, `json` | | `--only-structure` | Check only file structure. | `compare`, `dir` | | `--only-json` | Check only `json` structure. | `compare`, `dir` | ### Example with flags: ```bash fjv compare ./public/locales en --only-warn --only-show-errors ``` Will not exit with an error if there are any differences in files, and will display only the differences. ```bash Directory structure: (1 errors) ./public/locales/pl -buttons.json Json content: (3 errors) ./public/locales/ger/common.json -calc.minus -calc.equal +no ``` ## CI This may be used in CI, for example, what I do is add to the `package.json` script: ```json "scripts": { "translation-check": "fjv compare ./public/locales en" } ``` I run it in CI just like tests or a linter. If something is wrong, it will break your workflow. Developers can also use the script to verify if everything is correct when they make changes to translations. # API If you prefer to use it differently, you can also use it in your node project. There are a few functions (with types) that are exported. ```ts import { compareJsonsInDirs, compareDirectoriesContent, compareJsonsFiles, compareJsonObjects, } from "file-json-validator"; ``` * `compareJsonsInDirs` - compare `json` files in directories. * `compareDirectoriesContent` - check if directories have the same files. * `compareJsonsFiles` - compare `json` files. * `compareJsonObjects` - compare `json` objects. # Summary npm package `file-json-validator` helps validate file structure and `json` keys - it can be used for translations in applications. It provides CLI commands to compare directories and `json` files with some flag so you can customize your experience with it. Easy to integrate into CI workflow for automating validation.