Documentation.

What is Cognates?

Cognates is a command line tool and local browser editor for JSON translation files. It helps you create a default locale, add languages, edit strings, generate a TypeScript shape, and check translations for problems.

It works with React projects and other apps that use JSON locales. Your app still decides how to load a locale and display translated text at runtime.

Requirements

• Node.js 20 or newer
• npm
• A project where you can keep JSON locale files

Run all Cognates commands from your app's root directory, where its package.json and cognates.config.js live.

Quick start

1. Install the package in your project.
2. Run setup and accept the prompt to create the config file.
3. Add source strings to the new default locale JSON file.
4. Start the browser editor.

npm install --save-dev cognates
npx cognates setup
npx cognates start

Setup creates cognates.config.js and, if it does not exist, cognates/en.json. By default the editor opens at http://127.0.0.1:2410. If it does not open automatically, visit that address in your browser.

For example, put this in cognates/en.json:

{
  "home": {
    "title": "Hello {name}",
    "action": "Continue"
  }
}

Keep {name} in every translation of home.title. Cognates checks placeholder names when you run check.

Project file layout

your-app/
├─ package.json
├─ cognates.config.js
└─ cognates/
   ├─ en.json       # Default language
   ├─ fr.json       # Another language, after you add it
   └─ locale.ts     # Created by generate-type

The locale directory is set by localeDir, and the default file name comes from defaultLanguage. Store the files in version control with the rest of your app.

Configuration

Cognates reads cognates.config.js in the current directory. Setup writes an ES module config when your package has "type": "module"; otherwise it writes CommonJS.

ES module example

import { defineConfig } from 'cognates';

export default defineConfig({
  defaultLanguage: 'en',
  autoDetectLanguage: true,
  source: 'src/',
  port: 2410,
  localeDir: 'cognates/',
  excludePaths: ['/assets/*'],
});

CommonJS example

const { defineConfig } = require('cognates');

module.exports = defineConfig({
  defaultLanguage: 'en',
  localeDir: 'cognates/',
  port: 2410,
});

defineConfig fills in omitted fields with defaults. You can edit the config in the browser settings screen or in this file.

Using the local editor

Run npx cognates start, then use the Overview, Localize, and Settings links in the browser app.

Edit translations

1. Open Localize. Each JSON locale file appears as a language tab.
2. Select the default language to add keys and nested groups or edit the source text.
3. Select another language to fill in its translation values. Missing or empty values display the default text as a fallback in the grid.
4. Click Save after editing. If you switch tabs with unsaved changes, the editor warns you.

Add a language

Click Add locale, choose a language, and confirm. Cognates creates a new JSON file with the same keys as the default locale and empty string values. Translate those values, then save.

Rename a key

Edit a key in the default language. On save, Cognates asks you to confirm the rename and then updates that key across locale files. Review the affected files in version control afterward.

Change settings

Open Settings to change the default language, source path, locale directory, excluded paths, or editor port. The app writes the changes to cognates.config.js.

Command reference

Run these in the project root. Both the cognates and @akshay-rajput/cognates package names, when installed, expose the same cognates executable.

Validation & CI

check reads each non-default JSON file in localeDir. It reports:

• Missing and extra keys, including nested keys and array entries
• Empty translation strings
• Unexpected value types
• Missing or extra placeholders such as {name} and {0}

npx cognates check
npx cognates check --strict

The regular command reports issues in the terminal. The strict form gives CI a nonzero exit code when it finds issues. Both also fail when configuration or a locale file cannot be read.

Example package script

{
  "scripts": {
    "check:locales": "cognates check --strict"
  }
}

Then run npm run check:locales in your build or CI workflow after dependencies are installed.

TypeScript type generation

Run npx cognates generate-type after changing your default locale. Cognates writes locale.ts in the same directory as that JSON file.

For the quick start example, the generated shape is equivalent to:

export default interface Locale {
  "home": {
    "title": string;
    "action": string;
  };
}

Saving the default locale or confirming a key rename in the editor also triggers type generation. Run the command directly whenever you want to refresh the file yourself.

Using translations in your app

Cognates manages and validates JSON files. It does not provide a runtime translation component, language detector, or source code scanner. Load the JSON files with your framework or bundler, choose the active language in your app, and resolve keys there.

The config fields autoDetectLanguage, source, and excludePaths are saved settings for the workspace. They do not currently alter your application's runtime behavior.

Troubleshooting

“Config file not found”

Run npx cognates setup from your app's root directory, or create cognates.config.js there.

The editor cannot find the locale directory

Check localeDir and confirm it points to an existing project relative folder. Run setup to create the folder and default file.

The default locale is missing

Make sure the file name matches defaultLanguage, such as en.json for 'en'.

The editor port is busy

Change port in cognates.config.js, then restart npx cognates start.

Translations fail the placeholder check

Keep each placeholder name from the source string in its translation. For example, Hello {name} can become Bonjour {name}.

Frequently asked questions

Does Cognates translate text automatically?

No. It creates locale files and gives you an editor for their values. You or your translators supply the translated text.

Does it require React?

No. The local editor is built with React, but the CLI works with any project that uses JSON translation files.

Will it change my app's language at runtime?

No. Your app chooses how to load, select, and display translations.

Can I use the scoped package?

Yes, if @akshay-rajput/cognates is available in your registry. Install one package name; both provide the same CLI command. Setup writes a matching config import for the installed package.