
Localizing your product is a great way to reach new markets and generate more revenue. However, it will only be beneficial if you avoid the most common problems with localization.
There are some simple and easy-to-follow tips that you can utilize in order to make sure that your localization process is successful. 

## Give your texts enough space

If you have tight layouts, a rough rule of thumb is to double the English text and make sure it fits. 
Then you will usually have enough space for translations. 
Russian and German tend to have the longest translations, and the longest words. Get familiar with the shy-hyphen `&shy;` character. You put it in the word's HTML, and it will only break the word/show the hyphen when necessary. 
You can also Google: "[online hyphenation tool](https://www.google.com/search?q=online+hyphenation+tool)" 
so you know the appropriate places to break the word. Here are some example applications:

- [ushuaia.pl](https://www.ushuaia.pl/hyphen/?ln=en)
- [hyphenation24.com](https://www.hyphenation24.com/)
- [hyphenator.net](https://www.hyphenator.net/)
- [juiciobrennan.com/hyphenator](https://juiciobrennan.com/hyphenator/)

![number translations](/blog/number-translations-problem.jpg)

## Number translations

You need to translate numbers with decimals and commas because they are reversed in some languages.
For example: period appears as a comma, comma as a period.

If you are a JavaScript developer, then you can simply use 
[Number object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString) 
to format numbers. See example below:

```js
var exampleNumber = 123456.789;

exampleNumber.toLocaleString('pl-PL');
// output: 123.456,789

number.toLocaleString('ar-EG');
// output: ١٢٣٤٥٦٫٧٨٩
```

## Percent sign problem

Same goes for percent signs. Sometimes the % shows before the number, and not after also there might be a space between the number and percentage sign.
English style guides recommend writing the percent sign (%) following the number with no space between (e.g 50%) however this might differ for different languages.
- In Turkish and some other Turkic languages, the % sign precedes rather than follows the number without an intervening space.
- In Persian the % sign may appear before or after the numeric value, in either case without a space.
- In Arabic, the % sign is to the left of numbers as numbers are written from right-to-left. This means that the % sign is to the left of a number. Usually, there will not be a space between this % sign and the number.

## Watch out for Greek question marks
The Greek question mark (;) is often mistaken for a semicolon (;). 
The former marks the end of a sentence or phrase, while the latter is used to separate clauses in the same sentence.

![greek question makr](/blog/greek-question-mark-intelij-idea.png)

## Keep datetime in UTC 
- Always keep datetime in database in UTC. 
- Always return datetime from backend in UTC. 
- Adjust datetime on UI layer using timezone information from user or web browser. 
- Accept datetime in backend with any timezone.

You don't need any special library to format time from UTC to local for users. You can
use standard [JavaScript Date object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) like below:

```js
new Date('2010-10-04T09:48:11.000000Z').toLocaleString('en-US', {
  timeZone: 'Asia/Calcutta'
});
```

The main benefit to that is that the time is always guaranteed to be consistent. 
However, if you would like to reproduce some bug for user in different timezone it might be more challenging.
You will be forced to change timezone in your web browser to get the same data as your users sees. 


Localization: Tips & Tricks


## Background

In this article, I will show you how to create multi-language landing page in GatsbyJS.
I assume you already set up a Gatsby project, and we will start right from adding multi-language pages.

> Check our [template repository on GitHub](https://github.com/simplelocalize/multi-language-gatsby-example). 

## Install dependencies

I will use FormatJS library as it's one of [the most popular React library for internationalization](/blog/posts/the-most-popular-react-localization-libraries), and it plays nice 
with Gatsby plugin system.

```bash
# Npm users
npm install --save react-intl

# Yarn users
yarn add react react-intl
```

## Create i18n configuration file

Create a `i18n.js` file in your `src` directory to keep all i18n configuration in one place.

```jsx
const languages = ['en', 'pl', 'es'];
const defaultLanguage = 'en';

exports.defaultLanguage = defaultLanguage;
exports.languages = languages;
```

## Add utility functions

Create a new file with utility functions. I named it `linkUtils.js` and I put this next to `i18n.js` file in the `src` directory.

```jsx
import {defaultLanguage, languages} from "./i18n";

const getTranslatedPath = (pathname, to) => {
  const currentPageLanguage = getCurrentPageLanguage(pathname);

  let languagePath = '';
  const isDefaultLanguage = defaultLanguage === currentPageLanguage;
  if (!isDefaultLanguage) {
    languagePath = '/' + currentPageLanguage
  }


  let outputPath = `${languagePath}${to}`;

  const hasTrailingSlash = outputPath.endsWith("/");
  if (!hasTrailingSlash) {
    outputPath += "/";
  }

  return outputPath;
}

const getCurrentPageLanguage = (pathname) => {
  const pathElements = pathname.split("/");
  for (let element of pathElements) {
    for (let language of languages) {
      if (element === language) {
        return language;
      }
    }
  }
  return defaultLanguage;
};

export {getTranslatedPath, getCurrentPageLanguage};
```

- `getTranslatedPath` Function returns a route to a page with in the same language as current page.
- `getCurrentPageLanguage` Function returns language from current page path. 

## Create custom link component

In order to give a user to navigate through our website and keep the page language we need to create a custom `<a/>` element.

```jsx
import React from "react";
import {Location} from '@reach/router';
import {getCurrentPageLanguage, getTranslatedPath} from "./linkUtils";

const LinkTranslated = ({children = [], className = "", href = "/"}) => {
  return (
    <Location>
      {locationProps => {
        const {pathname = ""} = locationProps.location;
        return <a className={className}
                  href={getTranslatedPath(pathname, href)}
                  hrefLang={getCurrentPageLanguage(pathname)}
        >
          {children}
        </a>;
      }}
    </Location>
  );
};

export default LinkTranslated;
```

Now we can use `LinkTranslated` same as a regular `<a/>` tag from HTML.
We can pass a `href` property with base link to some page, and it will be converted into a translated link.

Learn more about [hrefLang attribute](/blog/posts/what-is-hreflang/).

> I used `Location` component from `@reach/router`, to get access to the `location` object. 

## Add a wrapper for `IntlProvider`

```jsx
import React from "react";
import {IntlProvider} from "react-intl";

function SimpleLocalize(props) {
  const language = props.pageContext.language;
  const messages = props.pageContext.messages;
  return (
    <IntlProvider
      locale={language}
      messages={messages}>
      {props.children}
    </IntlProvider>
  );
}

export default SimpleLocalize;
```

The main role of this component is to simplify a usage of `<IntlProvider/>` on every page.

## Add translations

Create a `i18n-translations.json` file with translations for all languages.

```json
{
  "en" : {
    "welcome-on-our-website" : "Welcome on our multi-language website",
    "hello-world" : "Hello World!",
    "about-us" : "About us",
    "learn-more-about-us" : "Learn more about us",
    "homepage" : "Homepage"
  },
  "pl" : {
    "welcome-on-our-website" : "Witamy na naszej wielojęzycznej stronie internetowej",
    "hello-world" : "Witaj Świecie!",
    "about-us" : "O nas",
    "learn-more-about-us" : "Dowiedz się więcej o nas",
    "homepage" : "Strona główna"
  },
  "es" : {
    "welcome-on-our-website" : "Bienvenido a nuestro sitio web multilingüe",
    "hello-world" : "Hola, mundo.",
    "about-us" : "Sobre nosotros",
    "learn-more-about-us" : "Más información sobre nosotros",
    "homepage" : "Página web"
  }
}
```

Managing a big JSON file like this might be hard and done only by a software team. This is the reason why we created 
[SimpleLocalize](/) where you can manage JSON files like this with ease, automatically upload and download them and use 
Google Translate or DeepL to auto translate the texts. [Try it for free for 7 days!](/register)

## Configure multi-language page generation

Now, edit your `gatsby-node.js` configuration file and override `onCreatePage` function like below.

```jsx
const messages = require("./i18n-translations.json")
const {languages, defaultLanguage} = require("./src/i18n");

exports.onCreatePage = async ({page, actions}) => {
  const {createPage, deletePage} = actions;
  return new Promise((resolve) => {
    let path = page.path;
    deletePage(page);

    for (let language of languages) {
      const isDefaultLanguage = language === defaultLanguage;
      if (!isDefaultLanguage) {
        path = '/' + language + page.path;
      }

      const pageForLanguage = Object.assign({}, page, {
        originalPath: page.path,
        path: path,
        context: {
          language,
          messages: messages[language]
        }
      });
      createPage(pageForLanguage)
    }
    resolve()
  })
};
```

A lot of things are happening here, right? Let start from the beginning.

- First of all, import `translations.json` file from root directory
- Use `deletePage` to remove default page created by Gatsby
- Iterate over all `languages` from `i18n.js` 
- Add `/{language}` to path if the language is not the default one
- Get translations for given `language` from `messages` object
- Add language and messages to a page context
- Use `createPage` to recreate a page with a new path and translations



## Create a first multi-language page

Create `index.js` in `/src/pages` directory and paste code below:

```jsx
import React from "react";
import {FormattedMessage} from "react-intl";
import LinkTranslated from "../LinkTranslated";
import SimpleLocalize from "../SimpleLocalize";

function IndexPage(props) {
  return (
    <SimpleLocalize {...props}>
      <h1>
        <FormattedMessage
          id="hello-world"
          defaultMessage="Hello World!"
        />
      </h1>

      <p>
        <FormattedMessage
          id="welcome-on-our-website"
          defaultMessage="Welcome on our multi-language website"
        />
      </p>

      <LinkTranslated
        className="btn btn-link"
        href="/about"
      >
        <FormattedMessage
          id="learn-more-about-us"
          defaultMessage="Learn more about us"
        />
      </LinkTranslated>
      <ul>
        <li><a href="/">English (Default)</a></li>
        <li><a href="/pl/">Polish</a></li>
        <li><a href="/es/">Spanish</a></li>
      </ul>

    </SimpleLocalize>
  );
}
export default IndexPage
```

`SimpleLocalize` Component will provide a `<IntlProvider/>` and `intl` object for `<FormattedMessage/>` components.

## Create second multi-language page 

Create file `about.js` in `/src/pages` directory and paste code like below:

```jsx
import React from "react";
import SimpleLocalize from "../SimpleLocalize";
import {FormattedMessage} from "react-intl";
import LinkTranslated from "../LinkTranslated";

function AboutPage(props) {
  return (
    <SimpleLocalize {...props}>
      <h1>
        <FormattedMessage
          id="about-us"
          defaultMessage="About us"
        />
      </h1>

      <LinkTranslated
        className="btn btn-link"
        href="/"
      >
        <FormattedMessage
          id="homepage"
          defaultMessage="Homepage"
        />
      </LinkTranslated>
    </SimpleLocalize>
  );
}
export default AboutPage;
```


## Result

Now, start your project with `npm run develop` and you should see 

![Multi-language Gatsby project example](/blog/gatsby-multi-language-project.png)


## Code repository

Full code can be found on GitHub.

[https://github.com/simplelocalize/multi-language-gatsby-example](https://github.com/simplelocalize/multi-language-gatsby-example)



### Message extraction

![Uploading extracted translation keys to translation editor](/blog/uploading-extracted-translation-keys-in-json-file.jpg)

In the repository you will also find [additional scripts in `package.json`](https://github.com/simplelocalize/multi-language-gatsby-example/blob/master/package.json).

I installed `@formatjs/cli` as a `devDependency` to extract all translations and ids from `<FormattedMessage/>` components.

```
## npm
npm install --save-dev @formatjs/cli

## yarn
yarn add -D @formatjs/cli
```

I used [simplelocalize-cli](/docs/cli/get-started/) to upload found ids and download ready to use translations.

Scripts explanation:
- `npm run extract` script will extract translations to i18n-extracted.json
- `npm run sync` script will upload found translation keys from i18n-extracted.json and download the latest translations from the server to i18n-translations.json


> Once you change a translation in JSON file, you need to restart GatsbyJS to see the effect. Sometimes you might not see a changed translation, then you need to run `npm run clean` before `npm run develop`. 

### Editing translations in SimpleLocalize

Below you see a screenshot from example project which I [pushed on GitHub](https://github.com/simplelocalize/multi-language-gatsby-example). Now, I can manage all translations from one place, add more languages and use DeepL or Google Translate to automatically translate them and use in my Gatsby page. 


![Multi-language Gatsby project in SimpleLocalize](/blog/simplelocalize-gatsby-project.png)
Multi-language content with [properly used `hrefLang` attributes](/blog/posts/what-is-hreflang/) will score much higher in SEO results.

Did you notice the small gray icons next to translated texts? I used DeepL integration to auto-translate those texts. 😄


Translation Hosting

SimpleLocalize CLI

REST API

Customer-specific translations

Posts tagged with `i18n`

Localization: Tips & Tricks

How to create a multi-language website in GatsbyJS?