@fizzog/dish

(Deprecated) This project has moved to i18nish and is in the process of retooling.

D.I.S.H. - Dynamic Internationalization Scanner and Harvester

A developer tool for managing localization files. Includes support for scanning and analyzing project usage, detecting orphaned keys, and providing a streamlined process for handling localization files in your project.

Specifically, this project is designed to work with i18next and react-i18next by tracking usage of useTranslation and t('namespace:key').

Features

• Localization File Management: Easily manage and maintain your localization JSON files.
• Scanning: Automatically scan your project for localization key usage.
• Orphan Detection: Identify orphaned or unused localization keys.
• Usage Analysis: Detect missing or unreferenced keys and streamline the translation process.

Installation

To get started with @fizzog/dish, we recommend using @fizzog/create-dish, a tool that sets up everything for you with minimal configuration. Follow the steps below.

Step 1: Install

Run the following command to install and initialize dish in your project:

npm init @fizzog/dish@latest

yarn create @fizzog/dish

Step 2: Run the cli

npm run dish

Or leverage the package.json script that is optionally created.

Supported config options

dish.config.json

{
  "out": ".dish",
  "sourceGlob": "./src/**/*.{tsx,jsx}",
  "localeGlob": "./src/locales/**/*.json",
  "analysisFiles": ["used", "unused", "missing", "code", "index"],
  "debug": false
}

• out string - The output directory where locale specific files for missing, used, and used data will be created.

• sourceGlob string - The glob expression for finding files that make use of translation code. e.g. ts, tsx, js, jsx.

• localeGlob string | string[] - The glob expression for finding files that store translation text. A string or array is valid json["**/locales/**/*.json", "**/modules/**/locales/*.json"]

• analysisFiles string | string[] - What files should be generated when dish is run. options: used, unused, missing, code, index

• debug boolean | string[] – Need to troubleshoot? Set debug to true to see detailed logs of each data transformation step. Found something odd? Feel free to open an issue on the DISH repo. If string array, possible values are: json["scan", "validate", "index", "compare", "out", "config", "aliases"]

Example locale file

{
  "common": {
    "title": "Phasellus!",
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
    "very": {
      "deeply": {
        "nested": {
          "key": "here"
        }
      }
    }
  }
}

Example One

import { useTranslation } from "react-i18next";

export function Page() {
  const { t } = useTranslation("common");
  return t("subtitle");
}

missing.json

{
  "en": {
    "common.subtitle": {
      "value": null,
      "status": "missing",
      "reference": [
        {
          "file": "src/Page.tsx",
          "line": 5,
          "column": 11
        }
      ]
    }
  }
}

Example Two

import { useTranslation } from "react-i18next";

export function Page() {
  const { t } = useTranslation("translation", {
    keyPrefix: "very.deeply.nested",
  });
  return t("common:key");
}

code.json

{
  "src/Page3.tsx": [
    {
      "value": "very.deeply.nested.common:key",
      "loc": {
        "file": "src/Page.tsx",
        "line": 7,
        "column": 11
      },
      "status": "conflict",
      "note": "Do not use the keyPrefix option if you want to use keys with prefixed namespace notation."
    }
  ]
}

Changelog

[0.4.1] - 2025-04-28

• Add support for new analysis file index.json. index.json contains a composite of locale files and where they were loaded from. A snapshot in time just after the indexing step and before any other step is executed.

dish.config.json

{
  "analysisFiles": ["used", "unused", "missing", "code", "index"],
}

[0.4.0] - 2025-04-27

• Add support for template and binary string processing.
• Gracefully handle template or binary string with variables. Attempts to partially match.
• Reduce false positives within missing.json.
• Extra metadata added to some items that are logged to analysis files.

const { t } = useTranslation("translation", { keyPrefix: "ns3" });
const dynamic = "foo";
t(`very.${dynamic}`);
t("very." + dynamic);
return null;

[0.3.29] - 2025-04-26

• Add support for loading namespaces
• Rename sourceGlob config property to codeGlob. System is backwards compatible. With the first major version update sourceGlob will be removed.
• Stopped export of empty analysis files

// the t function will be set to first namespace as default
const { t, i18n } = useTranslation(['ns1', 'ns2', 'ns3']);
t('key'); // will be looked up from namespace ns1
t('key', { ns: 'ns2' }); // will be looked up from namespace ns2

[0.3.27] - 2025-04-26

• Added processing support for optional lng option

const { t } = useTranslation('translation', { lng: 'de' });

[0.3.22] - 2025-04-25

• Add support for code file creation to track code issues
• Add supoprt for code in config file

  "analysisFiles": ["used", "unused", "missing", "code"],

{
  "src/Page3.tsx": [
    {
      "value": "very.deeply.nested.common:title",
      "loc": {
        "file": "src/Page3.tsx",
        "line": 7,
        "column": 11
      },
      "status": "conflict",
      "note": "Do not use the keyPrefix option if you want to use keys with prefixed namespace notation."
    }
  ]
}

[0.3.20] - 2025-04-25

• Add support for multiple namespaces

useTranslation("common");
useTranslation(["common", "other"]);

[0.2.14] - 2025-04-24

• Added processing support for optional keyPrefix option

const { t } = useTranslation('translation', { keyPrefix: 'very.deeply.nested' });
const text = t('key'); // "here"