Localization (l10n) with type safety tutorial
Tags: typescript, javascript, localization, internationalization
Published: 2021-11-05 09:44:41

Most software projects start out in English since the majority of terms in software development are in English. The problem is that it is unlikely that every user will be comfortable with your app when it isn’t in a language that they use on a daily basis. This is where internationalization (i18n) and localization (l10) comes in.

The act of localizing an app is a common problem because of the dynamic nature, which stops tools like Google Translate from working. Therefore a large wealth of internationalization tools exists solves the problem in various ways, but in this tutorial I am going to showcase inlang which is a way to ensure type safety in your translations so you never miss a translation again.

If you would rather just give it a try without committing to a full project, give our interactive example a try in our GitHub repo.

For this tutorial I will go through how to install typesafe-i18n in a React JS project and connect to inlang, but similar methods can be found in documentations for any other JS framework. Once it has all been set up, it will be as seamless as just a few presses, just see it in action below!

![Alt text](https://miro.medium.com/max/1400/1*eW-MIWG_1u8_xb8M1XkLLQ.gif)

## Initialization

The first step consists of initializing the project with the necessary config files and optional vscode extension. This is done by installing the npm packages inlang and concurrently:

```
npm i --save-dev @inlang/typesafe-i18n-importer
npm i concurrently
```

Afterwards two config files should be created in the root directory, one for typesafe-i18n and one for inlang:

#### **`.typesafe-i18n.json`**
```JSON
{
  "$schema": "https://unpkg.com/typesafe-i18n@2.40.1/schema/typesafe-i18n.json",
  "adapter": "react"
}
```

#### **`package.json`**
```JSON
{
"scripts": {
   "start": "npx concurrently --kill-others 'react-scripts start' 'npx typesafe-i18n' 'npx @inlang/typesafe-i18n-importer'",
 },
}
```

Lastly an optional step if using Visual Studio Code is to use the inlang extension which allows key generation directly in the code, automatically creating the key, putting in the base translation and changing your source code to be using the correct key.

```
ext install inlang.vscode-extension
```
Next up is initializing internationalization by wrapping your app in <TypesafeI18n> like below:

#### **`_app.tsx`**
```javascript
{
ReactDOM.render(
  <React.StrictMode>
    <TypesafeI18n initialLocale="en">
      <App />
    </TypesafeI18n>
  </React.StrictMode>,
  document.getElementById("root")
);
}
```

That was it, we can boot it up by running npm start and everything else should be handled automatically! The typesafe-i18n package will start setting up the whole type safety environment, so keys can be validated while developing and all the base translations will be visible.

## Coding flow

When using the Visual Studio Code extension, the only required steps to make new keys is simply to select the full text you want to translate, right click and send the inlang. This will handle everything, and you can continue your work, translations can be handled whenever you have time, or by someone else!

If using a different editor or IDE, do not worry, an extension for you is on the way. For now though, we would recommend everyone to use the extension as it is speeds up the process tremendously. In case you do want to stick with another editor, the process consists of creating the keys on the dashboard, which will automatically sync to the source code. Afterwards the key can be added like below:


```
function HelloWorld(props) {
    const { LL } = useContext(I18nContext)

    return LL.helloWorld()
}
```


Lastly, it is probably useful to be able to change the language. This is very simple and just means running setLocale() like below:



```
<button onClick={() => setLocale('de')}>Deutsch</button>
```


That was it, now you’re ready to localize your whole app doing nothing more as a developer! Head on over to the online platform at <http://www.app.inlang.dev> to write your translations, or let your non-technical teammates be in charge of all that. There will be an article for non-technical teammates on how to use the dashboard soon!

Feel free to star [inlang's GitHub Repository] (https://github.com/inlang/inlang), it helps us out a lot!