Description

The Metrists CLI is a command-line interface tool that gives you the freedom to store your localization files outside of your source-code.

Metrists cli is intended to be used with a internationalization library. We highly recommend that you use i18next with Metrists.

Table of Contents

• Installation
• GitHub
  • Setting up a repository
  • Connect your project
  • Private repositories
  • GitHub Enterprise
• Environment Variables
• Fetchers
  • Custom Fetchers
• Contributing
• Code of Conduct
• LICENSE

Installation

npm install -g @metrists/cli

Sync using a GitHub Repository

Setup a locals GitHub Repository

Create a repository with the following structure; or alternatively, clone our example repository.

en/
├─ default/
│  ├─ footer/
│  │  ├─ copyright.json/
│  ├─ welcome.json
fr/
├─ default/
│  ├─ footer/
│  │  ├─ copyright.json/
│  ├─ welcome.json

Metrists uses ISO 639-1 language codes standard for your top level folder names. Your second level of files/directories specify the localization namespaces. Inside each namespace, you can nested create directories and json files.

🌕 The file structure always follows the pattern: {language}/{namespace}/{file_key}.json.

The file /en/default/welcome.json contains the following content:

{
  "TITLE": "Metrists is great"
}

You can access the phrase TITLE using the key welcome.TITLE inside the default localization namespace.

You could also nest your files and directories as deep as you want. See the following examples:

| Language | namespace | key | Value | | -------- | --------- | --------------------- | ------------------- | | EN | default | welcome.TITLE | Local Repository | | FR | default | welcome.TITLE | Référentiel local | | EN | default | footer.copyright.TEXT | © 2023 Metrists CLI |

Connect Your Project to the Repository

Create a file called .metristssrc in the root of your repository:

{
  "resolvePath": "src/locals",
  "fetcher": "github",
  "fetcherParams": {
    "org": "organization-name",
    "repo": "repository-name"
  }
}

1. fetcher specifies the mechanisms that grab your localization files. In this case, we will be using github.
2. resolvePath is the path where your localization files will be store.
3. Specify your github repository and organization in fetcherParams. If you are using a personal account, your GitHub organization is your GitHub username.
4. In the root of your project, run:

metrists sync

✅ Your localization files are now synced with your GitHub repository.

Private Repositories

If you are using a private repository, you will need to create a GitHub Personal Access Token. You can create a token by following the instructions here.

Once created, you can provide it to the fetcher with the token parameter. You can also use Environment Variables to provide the token.

{
  "resolvePath": "src/locals",
  "fetcher": "github",
  "fetcherParams": {
    "org": "organization-name",
    "repo": "repository-name",
    "token": "github-token-here"
  }
}

GitHub Enterprise

Metrists by default will assume https://api.github.com as the API endpoint. If you are using GitHub Enterprise, you can specify the API endpoint with the baseUrl parameter:

{
  "resolvePath": "src/locals",
  "fetcher": "github",
  "fetcherParams": {
    "org": "organization-name",
    "repo": "repository-name",
    "baseUrl": "https://api.yourcompanygithub.com"
  }
}

Or as an Environment Variable:

{
  "resolvePath": "src/locals",
  "fetcher": "github",
  "fetcherParams": {
    "org": "organization-name",
    "repo": "repository-name",
    "baseUrl": "env.GITHUB_API_URL"
  }
}

Using Environment Variables as Fetcher Parameters

You can also use Environment Variables to provide fetcher params. Simply add env.[variable name] as the value of a fetcher parameter:

{
  "resolvePath": "src/locals",
  "fetcher": "github",
  "fetcherParams": {
    "org": "organization-name",
    "repo": "repository-name",
    "token": "env.environment-variable-name"
  }
}

Metrists will by default assume that your environment file exists in the root of your project, as .env. If you wish to change the path to your environment file, you can use the envPath parameter inside your .metristsrc file:

{
  "resolvePath": "src/locals",
  "fetcher": "github",
  "fetcherParams": {
    "org": "organization-name",
    "repo": "repository-name",
    "token": "env.environment-variable-name"
  },
  "envPath": "path/to/your/env/file"
}

Fetchers

Fetchers are mechanisms that grab your localization files. Fetchers are responsible for fetching the localization information from a source and outputting it in a JSON format.

The output of all fetchers should look like this:

{
  "[language]": {
    "[namespace]": {
      "[key]": "[phrase]"
    },
    "[another-namespace]": {
      "[key]": {
        "[key]": {
          "[key]": "[value]"
        }
      }
    }
  }
}

🌕 Phrase can be nested as deep as you want.

Custom Fetchers

If you wish to create your custom solution for storing your localization files, you can create your own fetcher. All your fetcher needs to do is to log a JSON version of your localization output:

console.log(
  JSON.stringify({
    en: {
      default: {
        title: 'Metrists is great',
      },
    },
  }),
);

Then you can call upon your fetcher file in your .metristssrc file:

{
  "resolvePath": "src/locals",
  "fetcher": "custom-fetcher.js"
}

Then run:

metrists sync

✅ Your localization files are now synced with your custom fetcher.

Contributing

This package is a beginner-friendly package. If you don't know where to start, visit Make a Pull Request to learn how to make pull requests.

Please visit Contributing for more info.

Code of Conduct

Please visit Code of Conduct.

License

MIT