Skip to content
This repository has been archived by the owner on Aug 15, 2023. It is now read-only.

Localization Guide

Jump to bottom
Benjamin Chanudet edited this page Aug 6, 2021 · 1 revision

How to translate this application

Because the official localization package from the Angular team builds as many artifacts as locales are declared, it doesn't suit the PWA requirements if you want access to several languages when you are offline. Something that could very much happen if you're crossing a border and you need to switch the application to English quickly.

As the application is quite small, and no complex algorithms are necessary (no need to handle plurals, variables, and so on), I created a small ngModule called I18nModule that exports a pipe for dates, and a directive for translating the application.

This guide will help you implement a new language into the application from scratch.

Clone the application on your computer

Fork the repository into your own account, then follow the Developing section of the README file to create a development environment on your computer. Once you run the ng s -o command, your browser should open and display the homepage of the application.

Create a new locale file

Locale files are stored in the src/app/i18n/locales folder:

  • locale.ts defines the required interfaces, and export the list of available locales.
  • locale.XX.ts exports the list of translation for the language which ID is XX

Go ahead and create a new file locale.XX.ts where XX shall be the ID of your language. Its basic content should be

// Import the interface that we'll have to export
import { Locale } from "./locales";

// Register the Angular corresponding locale to use date formats
import ngLocale from '@angular/common/locales/XX';
import { registerLocaleData } from "@angular/common";
registerLocaleData(ngLocale);

// Export the locale
export const locale: Locale = {
  id: 'XX',
  dateFormat: '',
  translations: []
}

If you language has a corresponding locale in Angular, you should import it to use the date format already defined there. This date format will be then used by the i18nDate pipe to display the dates in the correct language. If Angular doesn't provide a locale for your language, you can let it empty or put 'en-US' as a fallback.

Make your locale available on the application

Open the file src/app/i18n/locales/locales.ts. Import your locale at the start of the file

import * as xx from './locale.xx';

Then add the language in the AVAILABLE_LANGUAGES array

export const AVAILABLE_LANGUAGES: Language[] = [
  {id: 'en', name: 'English', locale: { id: 'en',  dateFormat: 'en-US',  translations: []}},
  // Other languages here...
+  {id: 'xx', name: 'xxLanguage', locale: xx.locale}
];

Save all the files. The application should refresh on your browser. If you click on the settings icon at the top right of the window, you should be able to select your language in the Language dropdown.

Add translations

The application is now using "your" language, but everything is displayed in English! That's because the translations array of your locale is empty, so the i18nModule falls back to English.

Open your browser console (usually with the F12 hotkey), in the Console tab you should see a bunch of warnings similar to this:

No translation for 'home-title'

That means that the i18nModule did not find a translation with the key app-home-title in your translations array. To fix this, add the following line to your translations array:

export const locale: Locale = {
  id: 'fr',
  dateFormat: 'fr-FR',
  translations: [
+   {id: 'home-title', html: `Certificat Numérique COVID UE`},
  ]
}

Save the file again. Your browser should refresh, and now the title of the page is displaying your text. And the warning has disappeared. Now you just have to do the same for every other warning. You can also check the full list in the locale.fr.ts file, to see if you've missed some translations that shouldn't appear very often (like errors and so on).

Give yourself some credit

You have filled in every necessary translations? Make sure you get the credit for your hard work, open the home page component src/app/content/home/home-page/home-page.component.html. Add your name to the list of translators:

  <ul class="translations">
    <li >
      <span class="ti ti-vocabulary"></span>
      <span appIntl="home-authors-french">French: Benjamin Chanudet</span>
    </li>
+    <li >
+      <span class="ti ti-vocabulary"></span>
+      <span appIntl="home-authors-xx">XX: Your name or whatever</span>
+    </li>
  </ul>

Send for evaluation and merging

Only a few instructions left and we'll be all set. To make sure you didn't mess with the application, run these commands:

ng lint
# should find no errors nor warnings
ng build
# should build successfully

If everything is fine, then you can commit your locale and create a Pull Request to have it evaluated and merged into the main branch. The build job will then deploy it on the official website https://covid-certificate.app

Thanks!

Thank you for taking some of your time to provide translations to this open source project.

If you have any trouble translating the application in your language, or feel a feature is missing in this very basic localization module, feel free to file an issue so we can discuss it altogether.

Clone this wiki locally