Internationalization (i18n)

Overview

Currently the SpeakHer website supports two locales*:

• English
• Japanese

We are open to supporting other languages if there is translation support and interest (Sorry, no Klingon).

• Note we use the term "locale" rather than "language".

Technical Implementation

Vue-i18n Basics

Translations are configured using Vue-i18n.

You can find the relevant code under /web/src/i18n:

/i18n:
 +- /locales
     +- en.json
     +- ja.json
 +- i18n.js 

i18n.js contains the configuration for Vue-i18n. It's imported by main.js and passed into the Vue instance. Under locales, we see the translation files. These are in JSON format of translation keys and values. The two-letter codes (en, ja) come from ISO-639-1.

Example of translation keys

For instance, here are the keys and values for the 404 Not Found Page in English:

"404": {
    "body": "Uh oh, we couldn't find that page",
    "goHome": "Take me back home",
    "title": "404: Page Not Found"
}

And Japanese:

"404": {
    "body": "そのページは存在しません",
    "goHome": "ホームに戻る",
    "title": "404：ページが見つかりません"
}

Now let's take a look at web/src/views/NotFound404.vue. Notice the $t function. This is a special function that looks up the key under 404, then under title, and inserts the value. The vue-i18n library keeps track of which locale is active.

<template>
  <v-container>
    <h1>{{ $t('404.title') }}</h1>
    <p>{{ $t('404.body') }}</p>

    <a href="/"><h2>{{ $t('404.body') }}</h2></a>
  </v-container>
</template>

When the browser renders the page, the user sees real text rather than variables.

Fallback

The "fallback" language is English. This means if a translation key is missing from the ja.json file, the English translation will be shown instead. For coding new features, it's okay to just add the English key. Please add a follow-up issue to add the missing translation, and we'll get a volunteer to help out.

Eslint plugin for vue-i18n

We use an [eslint plugin(https://eslint-plugin-vue-i18n.intlify.dev/) to avoid adding raw text (e.g. text without a provided translation) to the document. You may notice these errors or warnings when coding.

Locale Switcher

The component for changing the locale is in web/src/components/LocaleSwitcher.vue. It is currently a toggle because we support two languages. If we add a third, we may need to redesign it to a drop-down.

It is not good UX to guess the user's locale based on IP address location. If we'd like to infer the user's preferences, it's possible to get this information from the browser header.

Remembering the user's choice

If we refresh the page, the Vue instance would be recreated, and defaults reset. This wouldn't make for a good user experience, so we cache the user's choice in local storage. This logic is in web/src/components/LocaleSwitcher.vue

Non-Technical notes for Translators

We welcome contributions from fluent or native-level speakers, regardless of technical skill.

Notes on how to contribute are coming soon! In the meantime, please add a comment or get in touch. Thanks!