FAQ

🗂 Directory Structure

Your locales directory can be structured like this with zero-configuration

  locales         # i18n, langs, locale are also acceptable
  ├── en.json
  ├── de-DE.json
  ├── zh-CN.yml   # YAML
  ├── zh-TW.ts    # You can mix different formats
  ├── ...
  └── <country-code>.json

or

  locales
  ├── en
  |   ├── common.json
  |   ├── buttons.json
  |   ├── ...
  |   └── <filenames>.json
  ├── de-DE
  |   ├── common.json
  |   ├── buttons.json
  |   └── ...
  └── <country-code>
      ├── common.json
      ├── buttons.json
      └── ...

For more complex structures, please check out Path Matcher.

👍 Recommended Setup

To get the best experience from this extension (and other translation services as well), We recommend you use the following setup:

• Use JSON or YAML as your locale files. (Although other formats are supported as well, JSON and YAML works best for statistical analysis)
• The following configuration allows you to stay synced through all the locales.

{
  "i18n-ally.sortKeys": true,
  "i18n-ally.keepFulfilled": true,
}

❓ The extension doesn't work/show up (There is no icon in Activity bar)

This extension support numerous frameworks. Be sure the framework you are using is on the list.

Also, package.json is relied on to detect which framework you are using. It should be at the root of your project as well.

❓ I can see the icon in Activity bar, but nothing shows up

1. Locales path config missing. locales path will be detected automatically the first time you open a project. If nothing shows up, you may need to configure it manually. There are two ways to do that:
   • Open Command Palette (Ctrl-Shift-P or ⌘⇧P), type i18n Ally: Manual configure locales path then press enter and follow the guide.
   • Go to the settings of VSCode and set i18n-ally.localesPaths manually.
2. The source / displaying locale. The default locale is set to English(en). If you don't have English in your supporting locales, you may need to config it through command i18n Ally: Change source language
3. Check your Directory structure

📂 I am working on a monorepo and the extension can not detect my project

Usually, i18n ally looks for your package.json file at the root of your project. If you don't have it at the root, you can always specify the framework(s) you are using by i18n-ally.enabledFrameworks config.

🚩 Some Flag Icons are not Displayed

Due to the discussion in #313, flags should not be used to represent languages. From v2.2.4, we changed the algorithm of match flags, language codes (the first two-letter locales in BCP-47) will no longer be used as a factor to match flags.

We would suggest you use a more specific en-US form instead of the en for example. But if you would like to set flags for two-letter locales anyway, you can use the config:

"i18n-ally.localeCountryMap": {
  "en": "br", // show UK's flag instead of US's
  "zh": "cn", // show Chinese flag for 'zh'
  "ko": "ko", // show Korean flag for 'ko'
}

🔩 Advanced folder directory configurations

In some cases, you may use modules, monorepo or other philosophies to organize your locale files.

For example, you have the following directory structure need to be config.

  packages
  ├── pkgA
  |   └── i18n
  |       ├── en.messages.json
  |       ├── zh-CN.messages.json
  |       └── ...
  ├── pkgB
  |   └── i18n
  |       ├── en.messages.json
  |       ├── zh-CN.messages.json
  |       └── ...
  └── ...

The following config would make it work,

{
  "i18n-ally.localesPaths": [
    "packages/**/**/i18n"
  ],
  "i18n-ally.pathMatcher": "{locale}.messages.json",
}

Learn more about pathMatcher