/i18n-ally

๐ŸŒ All in one i18n extension for VSCode

Primary LanguageTypeScriptMIT LicenseMIT

logo

English | ็ฎ€ไฝ“ไธญๆ–‡

Visual Studio Marketplace Version Visual Studio Marketplace Downloads Visual Studio Marketplace Installs Marketplace Trending Monthly
GitHub last commit GitHub issues GitHub stars

Rails i18n is now supported! ๐ŸŽ‰

--------

Vue i18n Ally is now i18n Ally! Please check out Changes and Migration


๐Ÿงฑ Supported Frameworks

Frameworks will be auto-detected when one of the dependencies can be found in the project.

Framework Status Trigger Packages
Vue โœ… vue-i18n, vuex-i18n, vue-i18next, nuxt-i18n
Vue SFC i18n โœ… @kazupon/vue-i18n-loader
React โœ… react-i18next, react-intl, next-i18next
Angular(ngx-translate) โœ… @ngx-translate/core
Flutter(flutter_i18n) โœ… flutter_i18n
Ember.js โœ… ember-intl
VSCode Extension โœ… @types/vscode, vscode
i18next โœ… i18next
i18nTag โœ… es2015-i18n-tag
Joomla โœ… joomla/application
Chrome Extension โœ… manual config by "i18n-ally.enabledFrameworks": "chrome-ext"
Rails โœ… rails-i18n
Angular(native) Vote Here
๐ŸŽŽ Custom โœ… For almost any frameworks! How to...

If you would like to make it work for frameworks not listed above, you can:

โšก Features

Inline annotation

Hover & Direct actions

Manage all translations in one place

Translations missing report

Multiple formats supported

Refactors & Auto translate

Extract translations from code

Annonation for JSON and YAML

General

  • Multi-root workspace supported
  • Remote development supported
  • Supports numbers of popular frameworks
  • Supports linked locale messages
  • i18n for the extension itself, of course. Translation List

๐Ÿ“œ Supported Locale Formats

Format Read Write Annonations Note
JSON โœ… โœ… โœ…
YAML โœ… โœ… โœ… Comments will NOT preserved*
JSON5 โœ… โœ… โŒ Comments will NOT preserved*
INI โœ… โœ… โŒ Comments will NOT preserved*
JavaScript โœ… โŒ โŒ Forced in readonly mode
TypeScript โœ… โŒ โŒ Forced in readonly mode

* Due to the limitation of yaml.dumps(#196) and JSON5.stringify(#177), comments in YAML and JSON5 will be OMITTED on any modification by this extension (editing, translating, etc). If you are using comments in your locale files, you can turn on readonly mode by i18n-ally.readonly to prevent lossing comments.

๐Ÿ“‚ Directory structure

You can have locales directory 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
  โ”œโ”€โ”€ ...
  โ””โ”€โ”€ <contry-code>.json

or

  locales
  โ”œโ”€โ”€ en
  |   โ”œโ”€โ”€ common.json
  |   โ”œโ”€โ”€ buttons.json
  |   โ”œโ”€โ”€ ...
  |   โ””โ”€โ”€ <filenames>.json
  โ”œโ”€โ”€ de-DE
  |   โ”œโ”€โ”€ common.json
  |   โ”œโ”€โ”€ buttons.json
  |   โ””โ”€โ”€ ...
  โ””โ”€โ”€ <contry-code>
      โ”œโ”€โ”€ common.json
      โ”œโ”€โ”€ buttons.json
      โ””โ”€โ”€ ...

โš™ Common Configurations

All fields should add prefix "i18n-ally." in the setting.

Field Default Description
sourceLanguage en The primary locale for the project. It will also be the source language on translating
displayLanguage en Displaying language in annotations and tree views
localesPaths auto Locales directory path, relative to root of the project. Can also be an array of paths. Glob patterns are acceptable
sortedKeys false Sorting keys alphabetically on saving
keystyle auto Key style in your locale files, can be flat({"a.b.c": "..."}) or nested({"a": {"b": {"c": "..."}}})
readonly false Work on readonly mode. Translating and editing will be disabled
annotations true Enabling inline annotations
keepFulfilled false Always keep all keys fulfilled with empty string
enabledFrameworks auto You can specify what frameworks support you would like to enable. If no value is set, the extension will detect frameworks automatically
indent 2 Indentation size for your locale files
tabStyle space Tab style for your locale files
promptTranslatingSource false Prompt to select source locale on translating every time. If set false, the source language in the config will be used

๐Ÿ”ฉ Advanced Configurations

Field Default Description
filenameMatchRegex null Accept a regex allows you to map the filenames. The first group in regex should be the locale code

โœŒ Recommend Setup

To get best experience of this extension (and other translation services as well). We recommend you to 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 statical analysis)
  • With following configurations allows you to keep synced through all the locales.
{
  "i18n-ally.sortedKeys": true,
  "i18n-ally.keepFulfilled": true,
}

๐ŸŒ Help translate this extension

This extension itself supports i18n as well, it will be auto matched to the display language you used in your vscode editor. We have supported following languages.

Language Maintainer Contributors
English @antfu @rubjo
Simplified Chinese (็ฎ€ไฝ“ไธญๆ–‡) @antfu
Traditional Chinese (็น้ซ”ไธญๆ–‡) @antfu
Norwegian (Norsk) @rubjo
Spanish (Espaรฑol) @Baltimer
Japanese (ๆ—ฅๆœฌ่ชž) @isdh
Dutch (Nederlands) @Niekvdm
Portuguese (Brazilian) @Ibcs16
Franรงais @Nicoxx45

If you would like to help translate this extension, you can do it by following steps.

  1. Fork this repo and clone it to you local machine
  2. Copy package.nls.json to package.nls.<locale-code>.json in the root of the repo
  3. Translate every single message in the new json file you created.
  4. You may also update the table above in README.md
  5. Commit changes and make a PR to this repo

We recommend you to use vscode with i18n-ally. It supports i18n for vscode extension development which can help you translate itself ๐Ÿ˜.

๐ŸŽฏ Troubleshooting

Extension doesn't work/show up (There is no icon in activity bar)

This extension support numerous of frameworks, be sure the framework you are using is in the list.

Besides, package.json is relied on detecting 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 show up

  1. Locales path config missing. locales path will be detected automatically at the first time you open a project. If the nothing show 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.
    • Goto 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.

Advanced folder directory configurations

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

For example, you have 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
  |       โ””โ”€โ”€ ...
  โ””โ”€โ”€ ...

You could change your config like this:

{
  "i18n-ally.localesPaths": [
    "packages/**/**/i18n"
  ],
  "i18n-ally.filenameMatchRegex": "^([\\w-]*)\\.messages\\.json",
}

๐Ÿ‘จโ€๐Ÿ’ป Thanks

This extension was inspired by think2011/vscode-vue-i18n, it can't be existed without @think2011's great work.

Support for Vue Single File Component (SFC) is powered by kazupon/vue-i18n-locale-message, which is created by the author of vue-i18n. Thanks for making this!

Also my great thanks to all the awesome contributors and YOU for reading this!

Lastly, I want to have a special thanks to my partner @iiiiiiines who have encouraged and supported me working on this project.

โ˜• Buy Me a Coffee

I made this project with heart โค

If you found it useful, you may consider buy me a coffee!

Open Collective

Donate via PayPal

๐Ÿ“„ License

MIT License ยฉ 2019-2020 Anthony Fu