i18n Without Pain Using This VS Code Extension
If you are a web developer, there is a high probability that you are internationalizing your apps or websites. If you don’t, the reason is one of those two: either you don’t need to, or you noticed how painful it was and gave up.
Whatever framework or set of languages you are using, you are always going back and forth between files, looking for translations, and figuring out which key is which. With JSON i18n files, you can’t even copy the entire key you created to paste it elsewhere, it’s a mess.
i18n Ally
Out of the box, i18n Ally is compatible with a lot of popular frameworks. If you are using one of them, it will be pretty straightforward to configure for you as most of the work will be automatically done by the extension’s initialization routine.
This extension is also compatible with every framework and custom code with minimal efforts if you follow the steps I will give you below.
What it does
This extension does a lot, but here are the two most basic and valuable features:
- Inline visualization of translations
- Inline creation and editing of translations without opening any i18n file
You can browse for other (incredible) features here on GitHub.
You can notice in the picture above that on lines 3 and 4, the translation keys are replaced with the translation in the selected language. That’s how they will appear unless your cursor is on this line of code, as it is the case on line 12. On hover, there will be a compact list of translations with a pencil icon to edit them. If you type a key that does not exist, you will be able to create it without opening any translation file.
How to set it up
The first time I discovered this extension it didn’t work out of the box for me and the custom framework we were using, so I just put it aside for months and went with manual internationalization.
I am so mad at myself for this because it’s actually extremely easy to configure.
First, when you install the extension, it will add the key `i18n-ally.localesPaths` to your project’s configuration file in `.vscode/settings.json`. This is an array of the paths in which the extension will look for translation files. Remove them and paste your i18n folder path. Mine looked like this (Angular project using JHipster):
"i18n-ally.localesPaths": [
"src/main/webapp/i18n"
]Then check your OUTPUT tab, and select i18n Ally to see if there is any error, but after a quick loading, you should start to get the extension running in all your files.
Add unsupported framework and custom code support
Don’t skip this step if you need anything more than the supported frameworks, because it is also fairly easy, and getting the extension to work in only half of your code is not really helpful.
In my case there were two problems: We use JHipster with Angular, which comes with a custom translation system building on Angular’s default one, and I created components taking i18n keys as parameters.
Both of those cases can be addressed by creating a basic i18n Ally custom framework support file. This file is essentially a list of escaped regular expressions to match every custom code your want to.
Create a new file `.vscode/i18n-ally-custom-framework.yml`. From the doc, here’s the sample configuration to copy and paste (including useful comments that you should keep in there for later use):
# An array of strings which contain Language Ids defined by VS Code
# You can check avaliable language ids here: https://code.visualstudio.com/docs/languages/overview#_language-id
languageIds:
- javascript
- typescript
- javascriptreact
- typescriptreact
# An array of RegExes to find the key usage. **The key should be captured in the first match group**.
# You should unescape RegEx strings in order to fit in the YAML file
# To help with this, you can use https://www.freeformatter.com/json-escape.html
usageMatchRegex:
# The following example shows how to detect `t("your.i18n.keys")`
# the `{key}` will be placed by a proper keypath matching regex,
# you can ignore it and use your own matching rules as well
- "[^\\w\\d]t\\(['\"`]({key})['\"`]"
# An array of strings containing refactor templates.
# The "$1" will be replaced by the keypath specified.
# Optional: uncomment the following two lines to use
# refactorTemplates:
# - i18n.get("$1")
# If set to true, only enables this custom framework (will disable all built-in frameworks)
monopoly: trueYou will have to make some changes depending on what you want to achieve:
- `monopoly` defines whether this file will be the only configuration used or if it will be used along with a supported framework configuration. Let’s say you want Angular AND your custom code, you will need `monopoly: false`.
- `languageIds` are the languages in which you want to detect translations. Language ids can be found here.
- `usageMatchRegex` are escaped regular expressions in which `{key}` refers to the i18n key to detect.
As an example, I wanted to use the Angular default configuration and add support for `jhiTranslate`, `labelI18nKey`, and `placeholderI18nKey` attributes in HTML files. This is the resulting configuration file:
languageIds:
- htmlusageMatchRegex:
- "(?:translate|jhiTranslate|labelI18nKey|placeholderI18nKey)=['\"`]({key})['\"`]"monopoly: false
Your configuration file should be detected on save by i18n Ally. Again, check your OUTPUT tab, and select i18n Ally to see if everything is fine.
Before you leave
Most of this article is just me getting you through the extension’s documentation. Check it out if you want to do further configuration or discover other features. It is well documented and easy to read.
I hope this will be as much of a game-changer to you as it was to me. Have fun internationalizing!
