TL: DR

npm package file-json-validator to validate file structure and json keys:

• https://www.npmjs.com/package/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:

./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:

• npmjs.com/package/file-json-validator

• 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.

pnpm add file-json-validator

CLI commands

There are a few commands that you can use depending on what you want to check:

Examples

If your file structure is like this:

./public
└── locales
    ├── en
    │   ├── buttons.json
    │   └── common.json
    ├── ger
    │   ├── buttons.json
    │   └── common.json
    └── pl
        └── common.json

Then you can use CLI:

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:

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.

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.

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:

Example with flags:

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.

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:

"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.

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.