Lost in Translation

Localisation in Vue with i18next

Sun, 12 May 2019 00:00:00 GMT

Localisation in Vue with i18next

Having worked a little with Vue recently, I came across i18next for localisation in Vue. I18next is an internationalisation-framework written in and for JavaScript. You can find some more info in their documentation pages.

I was curious if it was easy to set up, so I added to a little practice project I have been working on. The repository I used can be found here and the actual site is here.

To get started, set up a new project with vue create app-name. Then use npm install i18next @panter/vue-i18next or yarn add i18next @panter/vue-i18next to add i18next to your Vue project. Next set up i18next in index.js:

index.js

      
        import Vue from 'vue'
      
        import i18next from 'i18next'
      
        import VueI18Next from '@panter/vue-i18next'
      
        import App from './App.vue'
      
        import en from './locales/en.json'
      
        import de from './locales/de.json'
      
        const locales = {
      
          en: en,
      
          de: de
      
        }
      
        Vue.use(VueI18Next)
      
        i18next.init({
      
          lng: 'en',
      
          fallbackLng: 'en',
      
          resources: {
      
            en: { translation: locales.en },
      
            de: { translation: locales.de }
      
          }
      
        })
      
        const i18n = new VueI18Next(i18next)
      
        if (document.getElementById('app')) {
      
          /* eslint-disable-next-line no-new */
      
          new Vue({
      
            el: '#app',
      
            i18n: i18n,
      
            render: h => h(App)
      
          })
      
        }

view raw index.js hosted with ❤ by GitHub

Looking at the code in index.js above in detail, we are first importing i18next and @panter/vue-i18next, then we are using i18next.init to initialise it and set the resources. In my example I set English as my source and fallback language and German as additional language. I decided to store my text in .json files in a "locales" folder. The folder contains one file per language. Both files contain the same keys with text in the corresponding language.

en.json:

      
        {
      
            "message": "hello",
      
            "tryitfree": "Try it free",
      
            "readytobuild": "Ready to build your community?"
      
        }

view raw en.json hosted with ❤ by GitHub

And de.json:

      
        {
      
            "message": "hallo",
      
            "tryitfree": "Probiere es kostenlos",
      
            "readytobuild": "Bist du bereit, deine Community aufzubauen?"
      
        }

view raw de.json hosted with ❤ by GitHub

Now that we set up i18next and initialised it, it is available globally in our project and we can use $t in our various components to import our keys with their translations from the locale.json files into our components. And the great thing is you don't need to import anything else in the components, just use it.

      
        <button class="try">
      
           {{ $t("tryitfree") }}
      
        </button>

view raw Header.vue hosted with ❤ by GitHub

Last but not least we should give the user an option to change the language using i18next.changeLanguage. You can find more information about Panter i18next in the documentation.

Conclusion

The initial set up of the i18next plugin for Vue is very easy to implement. The documentation was straight forward and easy to follow. There are quite a few options that I haven't explored yet but certainly intend to in the near future. Have you used this plugin? What are your experiences?

Localisation in WordPress

Sun, 17 Mar 2019 00:00:00 GMT

Localisation in WordPress Part 1

Recently I have been looking into how to work with WordPress and I was curious if it is easy to localise your site once you have set up some content in it.

In this blog post I'm looking at how to localise the WordPress interface as well as content. If you are looking for information about how to prepare plugins for internationalisation, have a look at the WordPress documentation. I will not be covering this in this post.

Localisation happens after internationalisation and is important for everyone who is interested in localising their WordPress site. It's the process during which your theme and content get translated and adapted for a specific market and language.

There are two steps that you might be interested in:

How to use a localised version of WordPress
How to translate your content

How to use a localised version of WordPress

If you haven't installed WordPress yet, simply head over to their site WordPress.org and download your localised version of WordPress and unzip it in your preferred installation directory. Normally that's public_html. Then create a database for WordPress on your web server and add a MySQL user with all the necessary privileges. Next edit the wp-config.php file and add your database information. Finally run the WordPress installation by accessing the URL in a web browser.

If you already have WordPress installed and would like to change the language of the user interface, simply log into your dashboard, click on Settings > General, then scroll down to the bottom of your page to Site Language and select the language of your choice from the dropdown.

However, this will only change the language used in the backend of your WordPress site. All the content you have written as well as your theme and any plugins you use will remain in the language you set them up in. To translate content, you require a separate plugin.

Localisation Plugins

WeGlot

There are a number of plugins out there. When I looked up plugins, I initially tried out WeGlot, which has a free version available to test the setup. It was very easy to set up and intuitive to use. Once you create an account with WeGlot, they will take you through the setup step by step.

One drawback for me was that translations are edited in your WeGlot account rather than directly in WordPress.

Polylang

A second plugin I tried was Polylang. The plugin was very easy to set up. Simply install it via the plugins section and activate it. Once installed, you can set up the langauges you would like to localise into.

Here it's important to set up your base language (which in my case was English UK) first. This is especially important if you already have some content in your site. Once you have your base language, you can then add any number of additional languages. Once you set up your languages, you can then easily add the translation of your posts and pages via the editor.

Transposh

The third plugin I tried was Transposh. It took me a little bit longer to set up but once it's set up, it's incredibly easy to use.

To install the plugin, log into your dashboard, click on Plugins > Add New and search for Transposh, then install and activate the plugin. Next click on Transposh and go to the settings to enable the full version of your plugin. To do that simply tick the box at the top of the Settings page and save your change.

To update, simply click on Dashboard and Update. This will notify you that there is a new update for your plugins. Click on Plugins and install the updated version of Transposh.

Next go back to Transposh, click on Languages and click on the languages you would like to localise your site into. Don't forget to save to apply your changes. You can pre-translate into those languages by clicking on Utilities and selecting "Translate All Now". Once you have done that, make sure to proofread those translations as they are machine translations and probably extremely rough. To proofread, we need to enable the widget on the site first. Go to Appearance on your Dashboard and select Widgets, then look for Transposh and select where on your page you would like to show the Widget.

I added my widget to the footer. Once that's been added, you can then head over to your site and either add or edit the translations. Since I added the widget to the footer, I have to scroll all the way down to the footer and to find "Edit translations" with the flags for the languages I can update.

Once I click on the language (flag) I want to update I will see a lot of colourful marks on the page which indicate what content can be changed.

Simply click on what you would like to update or add and add your translations. There will most likely be some Google translated hints for you already.

Once you are done, click on the tick to save the translation. If you would like to see how many translations have been added, you can do so in the Dashboard by clicking on Transposh and on Translation Editor.

One thing you probably should check is who can add translations. Go into the Transposh settings and there right at the top you will see some check boxes. By default anybody can edit your translations, which is probably not what you want, so simply check the appropriate check boxes and then save your changes.

Conclusion

This is just a quick and simple overview on how to get started with localisation in WordPress. There are many more plugins out there. Some are free and some are paid. It's probably worth trying a few out and seeing which one suits your needs best. Have you done any localisation in WordPress? What was your experience? Let me know in the comments.

Software localisation into Arabic Part 2

Sun, 10 Feb 2019 00:00:00 GMT

Software localisation into Arabic Part 2

In my last blog post I talked about considerations about what language to choose when localising into Arabic. In this post I'd like to talk more about some technical challenges when localising into Arabic.

Arabic language interfaces present some particular challenges in relation to their visual design. Those challenges range from the obvious issue of the right to left (RTL) layout to other usability considerations related to images, icons and type font and size.

RTL

The Arabic writing system is bi-directional, cursive, and context dependent. Arabic text runs from right to left (RTL) but numbers and Latin text, such as global brand names are written from left to right (LTR). There are therefore mixed direction of text segments. So when building a search functionality, both Arabic and English text needs to be searchable. It could prove useful to accomodate common spelling mistakes in the search results.

Because Arabic is written right to left, applications will be read from the top right-hand corner and elements on the page need to be aligned to the right-hand side. Research has shown that user behaviour on Arabic sites mirrors the F-shaped reading pattern that is typical of users on English speaking websites. Users start reading in the top right hand corner, scan across the top and then down the right-hand side.

The BBC website is a very good example of the difference in layout between English and Arabic.

Images

Graphics and icons are also affected by text direction. However logos and icons are a good example of elements that keep their LTR alignment on an RTL website or application. International logos will often stay the same but icons that indicate a direction might change. Tables and charts are typically mirror-imaged horizontally.

You should carefully consider the images you choose to use in your application and how your users will perceive them. Keep in mind the different cultural and social norms and how these norms affect the perception of images you use.

Font & Text Size

Arabic characters are generally a bit shorter and wider than Latin characters. This means that they take up more space horizontally and they also need a bigger font size to be more readable. So take into account that you generally need at least 30% more space for Arabic text compared to English. You will probably find yourself resizing most dialog boxes in your content.

Arabic script is always cursive, whether handwritten or printed. Because it is cursive, 22 of the letters can take four different shapes depending on their position in a word and the surrounding characters: initial, middle, final or isolated position. The graphic below from arabicquick.com illustrates the different shapes of the letter ya depending on its position in a word.

Upper and lower case do not exist in Arabic. To emphasize or highlight words, use quotation marks. Abbreviations and acronyms are very rarely used. They should be translated in the full form they stand for (For example: RAM should be translated as ذاكرة الوصول العشوائي.

Numbers

Websites and software applications should support all Arabic regional standards, such as date/time/number/currency/address format and calendar information, as well as sorting and indexing rules. Arabic numerals can be written in Hindi or Arabic digits.

Cultural considerations & translation

Many Arabs are Muslims. When you create content, take cultural and religious sensitivity into account (especially in graphics and images). Translators may also have restrictions concerning the content of the material they’re willing to translate. Most Arab countries do not work on Fridays and Saturdays. Their work week begins therefore on Sundays.

Terminology management is extremely important in the localisation process into Arabic. One of the first steps should involve solving the issue of terminology - a glossary should be created. Only experienced Arabic translators with an expert knowledge of the field can accurately create custom Arabic terms which will be understood by your target audience.

Conclusion

The demand for localising websites and apps into Arabic is increasing. Yet there are many challenges, both of technical and linguistic nature. While researching culture and established standards of web design and usability are a good starting point, you should consider doing user research with real end users in your target markets to create a usable product with a great user experience.

Software localisation into Arabic Part 1

Fri, 08 Feb 2019 00:00:00 GMT

Software localisation into Arabic Part 1

If you want to be successful online, you need to design for good user experience. That means if you are creating a website for Arab users, you need to apply UX and usability considerations that are specific to your target audience in that region.

A great user experience will make users return to your website or app. If the experience is poor, they simply won't.

Arabic is the fifth most widely spoken language throughout the world. It's mostly spoken in the Middle East and North Africa. It is one of the oldest languages and is the official language in 26 countries. However, it is very under represented when it comes to the internet.

The written word is always going to be the backbone of any website or application. When users find it difficult to understand the content of your website or app, they will become frustrated and dissatisfied.

Arabic tends to be a more 'wordy' language than English. Often certain English words or phrases cannot be translated into Arabic directly and they have to be described rather than translated word by word. This can lead to problems when there is only limited space available, e.g. on a mobile screen.

It is also important to remember that there is no single form of Arab culture and language. There are three forms of Arabic: Classical or Qur’anic Arabic, Modern Standard Arabic and Spoken or Colloquial Arabic.

Modern Standard Arabic derives from classical Arabic. It is the language that is taught in schools and universities and it is used in news media, literature, science and technology and for administrative purposes across North Africa and the Middle East. This language is a written language only and can be perceived as quite formal.

If your website or application uses quite a formal tone overall, this might be the language to use for your translations. If on the other hand you are using a more chatty tone, then translation will be a lot harder because there are various forms of spoken Arabic. Some of these dialects are similar while others are mutually incomprehensible.

Deciding on the form of Arabic you use will be influenced by a number of different factors:

-- Are your target users based in a single country or are you targeting the whole region?
-- Do you have the resources and capabilities to have your website or application cater to local dialects?
-- What’s the tone of voice that you want your website or application to convey?

It’s important to fully understand who your target users are and then make your decisions accordingly.

Have you had any experience localising into Arabic? Let me know in the comments.

Detecting user locales in JavaScript and React

Fri, 11 Jan 2019 00:00:00 GMT

Detecting user locales in JavaScript and React

Detecting the location of your website’s users is useful for a variety of reasons. You might for instance want to display different content, perhaps in different languages for people from different countries, or display targeted information to visitors from different locations.

What is a user locale?

A user locale indicates which default settings a user wants to use to format dates, times, currency, and large numbers. The user locale is not the language. The only influence the user locale has on the language is on the names of the days and months. For example, if you use the long date format to display "November 25, 2018," the "November" string will change based on the user locale. When the user locale gets changed, it adds an input locale with all the default settings for the associated language. Applications and websites should use these settings to present data to the user.

There are different ways to detect a user locale:

-- Geo IP
-- Accept-Language request header

Geo IP refers to the method of locating a computer's geographic location by identifying its IP address. A lot of websites use Geo IP to guess the location users are visiting from. IP Location Finder is an easy demo for information that can be gathered that way.

This approach can be quite expensive to implement and it is not always accurate either. In today's world people travel a lot, which means their location doesn't necessarily represent their desired locale.

The Accept-Language request HTTP header provides information about the languages that the user is able to understand and about what locale the user prefers. Browsers set this information based on their user interface language. Users are able to change this but they rarely do.

Using the Accept-Language header is a good starting point for determining the language of the user. Originally the Accept-Language header was intended to specify a user's language. But because a lot of applications also need to know the locale of a user, Accept-Language has been used to determine this information.

If you use Accept-Language to determine this information, you should give the user an option to override the language and cultural settings if they would like to do so. The information in Accept-Language header might might be out of the user's control if they are travelling and are using an internet cafe or they are borrowing a friend's computer for example.

In React you can easily use the accept-language package. This package extracts user locales from HTTP headers and compares them to the ones you offer on your website. If none of the locales match, then the default locale of your website will be used.

To use the package, install it with npm or yarn:

npm install --save accept-language  npm install --save cookie-parser js-cookie

Next import the libraries in the server.js file and set it up as follows:

import cookieParser from 'cookie-parser';
import acceptLanguage from 'accept-language';

acceptLanguage.languages(['en', 'de']);

const app = express();

app.use(cookieParser());

function detectLocale(req) {
  const cookieLocale = req.cookies.locale;

  return acceptLanguage.get(cookieLocale || req.headers['accept-language']) || 'en';
}
…

app.use((req, res) => {
  const locale = detectLocale(req);
  const componentHTML = ReactDom.renderToString(<App />);

  res.cookie('locale', locale, { maxAge: (new Date() * 0.001) + (365 * 24 * 3600) });
  return res.end(renderHTML(componentHTML));
});

In the example both English and German are accepted locales. The detectLocale function looks first for a locale from a cookie and if there is none, it will fetch the information from the Accept-Language header.

If you just need the user's preferred language, the window.navigator object contains a read-only property navigator.language that returns a string representing the preferred language of the user, which tends to be the language of the browser user interface.

var lang = window.navigator.language

Conclusion

User locales are useful to answer questions such as:

-- What numeric formats does the user expect?
-- How should dates and times be formatted?
-- What is the user's preferred language?
-- What is the user's time zone?

There are different ways to determine this information, however, none of them are 100% perfect. Whatever way you decide to implement your user locale detection, give the user an option to change it because people borrow from friends or use internet cafes and should be allowed to pick their own preferences.

Localisation and web accessibility

Sat, 29 Dec 2018 00:00:00 GMT

Localisation and web accessibility

Web accessibility means that websites and tools are designed and developed so that anybody even if they have any disabilities can use them. More specifically, people can perceive, understand, navigate, interact with and contribute to the web. Web accessibility is also beneficial for people without disabilities.

For example, a key principle of web accessibility is designing web sites and software that are flexible enough to meet different user needs, preferences, and situations. Sometimes such flexibility also benefits people using a slow internet connection or people with "temporary disabilities", such as a broken arm, and people with changing abilities due to aging.

Internationally, a number of initiatives such as Web Content Accessibility Guidelines (WCAG) have been implemented to develop guidelines for web accessibility to generate content that is usable by everybody.

The WCAG guidelines aim for perceivability, understandability, operability and robustness. Here are some of the things that can be done to improve the accessibility of a website.

Perceivability

Provide captions, text or other alternatives for non-text content.
Create content that can be presented in different ways without losing meaning.
Make it easier for users to see and hear content.

Understandability

Make text readable and understandable.
Make content appear and operate in predictable ways.
Help users avoid and correct mistakes.

Operability

Make all functionality available from a keyboard.
Make it easy to use inputs other than keyboard.
Help users navigate and find content.
Give users enough time to read and use content.
Do not use content that causes seizures or physical reactions.

Robustness

Content must be robust enough that it can be interpreted reliably by a wide variety tools, including assistive technologies.
As technologies and tools evolve, the content should remain accessible at all times.

All these guidelines can be found with detailed descriptions on the W3 website.

How does localisation fit into the criterias mentioned above?

Perceivable

Many websites provide an increasing amount of content that is not text-based, such as images, sound, video and interactive controls. These elements are not perceivable for every user and therefore a text alternative has to be provided. This text alternative can then be presented in a way that they can perceive, that is, auditory (text-to-speech), tactile (Braille) or visual (displayed on the screen) output. When localising accessible web content it is essential to not only to localise the original content, but also to pay special attention to localising the alternatives to that content.

Another perception-related issue is the sequence of the content. If the sequence in which content is presented to the user influences its meaning, then a correct reading sequence should be available to screen readers. Reading sequences are not necessarily the same in all languages, so special attention should be paid to correctly localising the reading sequence.

Some websites use background audio to present their content. WCAG recommends that a user has access to versions of speech content in which there is no background audio or the background audio can be turned off. If such content is present, localisation can add dubbed speech in the target language which should work as foreground audio and should be at least 20 decibles louder than the background audio if present.

Understandable

The key issues for localisation under the understandable principle are related to language identification, unusual words, reading level, pronunciation, error management and help.

It is important to identify the human language used on a website, so software can correctly handle language changes and present information to the user. When the language is set correctly screen readers can present the content in that language and search engines will find pages in a user-defined language. During the localisation process the language of the page and language of parts should be clearly defined.

Unusual words and abbreviations can make it difficult for the users to understand the web content and should be defined appropriately. Such unusual words, idioms and jargon should either be avoided or defined. Abbreviations or acronyms should have their meaning or expanded form. These should also be maintained in the localised content.

Generally text should not require a more advanced reading ability than the lower secondary education level as defined in (UNESCO, 1997). If for some reason this is not possible, then the developers should provide an additional version of the text with lower reading ability requirements. This is an important requirement for people with reading difficulties. The reading level of the original content should be maintained during the localisation process.

Labels, instructions and help related to interactive content, such as forms should be clear and precise. This is a key issue for people with comprehension difficulties as well as screen reader users. Always indicate clearly which form elements are mandatory so that users know what needs to be completed. When localising interactive elements, special attention should be paid to making the localised labels, instructions and help useful for the intended users.

Web content should prevent errors, identify any mistakes made and, finally, make suggestions to help users to correct errors. When localising the error management content, care should be taken that the correct terminology and formatting of the target language and region are used.

Operable

The key issues for localisation under the operable principle are related to page titles, focus order, link purpose and headings.

All web pages should be titled. Titles appear in the title bar of the web browser and also appear as the website name when storing bookmarks. When localising a page, special attention should be paid to the page title in order to maintain the information provided by the original version of the content.

Focus order is the order in which the components of a web page receive focus when pressing the tab key. WCAG states that the focus order should preserve meaning and operability to ensure that keyboard users have a similar experience to users of pointing devices. When localising, it is important to bear in mind whether the target language has a different reading order and/or direction than the source language. If it does, localisation specialists should ensure that the focus order does not change the meaning and operability.

Link content (the text and/or image) should clearly indicate where the user will go or what will happen when clicking the link. This is useful for people with cognitive impairments and for people (like blind or deaf-blind people) that use link-based browsing, which only navigates through the links, rather than the full page. When links get localised, special care should be taken to provide adequate information about the purpose of a link.

Overall headings, labels and section headings should clearly represent their purpose, so users can easily navigate through the structure of a page. This is useful for people using the keyboard or for people with cognitive impairments. Therefore pay special attention to the descriptions contained in headings, labels and sections when localising a page.

Conclusion

In conclusion localisation of content is necessary to maintain or increase the accessibility of web content for a wider audience. This will benefit all users and not just users with certain disabilities.

React Hooks

Sat, 03 Nov 2018 00:00:00 GMT

React Hooks

The React team recently introduced a new feature in version 16.7.0-alpha - React Hooks. A lot of chatter in various React forums made me want to have a look what React Hooks are all about, so I went ahead and tried a few of them out. I should mention that they are currently still an experimental proposal and their implementation may change. It's worth keeping an eye on the official documentation for the latest update on this new feature.

React Hooks were introduced to let you use state in stateless or functional components. Using Hooks you no longer will have to change your component into a class if you need state.

A number of Hooks are already built into 16.7.0-alpha:

useState
useEffect
useContext
useCallback
useMemo
useReducer
useRef
useLayoutEffect
useImperativeMethods
useMutationEffect

You can also create custom Hooks.

To start using React Hooks, first use npm or yarn and install version 16.7.0-alpha.

yarn add react@16.7.0-alpha.0
yarn add react-dom@16.7.0-alpha.0

I created a small practice repository on Github where you can find all the code that appears in this post.

State hooks

Without a state Hook you'd have to create a class to keep track of count and its state in the component below:

import React from 'react'

class Counter extends React.Component {
  this.state = {
    count: 0
  }
  const [count, setCount] = useState(0)

  render() {
    return (
      <div className='counter'>
        <button onClick={() => this.setState({ count: this.state.count + 1 })}>Click me</button>
        <p>You clicked the button {this.state.count} times.</p>
      </div>
    )
  }
}
export default Counter

State Hooks simply let you use state inside a functional component.

import { useState } from 'react'

function Counter() {
  const [count, setCount] = useState(0)

  return (
    <div className='counter'>
      <button onClick={() => setCount(count +1)}>Click me</button>
      <p>You clicked the button {count} times.</p>
    </div>
  )
}
export default Counter

Above, useState is the Hook. React will preserve the local state of the variable count in between re-renders. UseState has only one argument (0) - because the counter starts from 0. 0 is only used on the initial render.

Effect hooks

Effect Hooks are used to tell React that your component needs to do something after render. They run after every single render by default. If that's not quite what you want, this behaviour can be customised to suit.

import {useState, useEffect} from 'react'
import {getAllBooks} from '../apiClient'

function Books() {
  const [books, setBooks] = useState([])

  useEffect(() => {
    getAllBooks()
      .then(books => {
        setBooks(books)
      })
  })

  return (
    <div className='books'>
      <h2>Books</h2>
      <ul>
        {books.map(book => {
          return <li key={book.id}>{book.title}</li>
        })}
      </ul>
    </div>
  )
}
export default Books

In the example above useEffect is used to pass a function to fetch some book titles from a simple database. In a class based component the same function would have been called from within componentDidMount.

Custom hooks

You can also write some custom Hooks to use within your React components. The React team suggests prefixing Hooks with "use", just to make it easier to keep track of the types of components in your code.

usePrevious Hook:

import { useRef, useEffect } from 'react'

export function usePrevious(value) {
    const ref = useRef()
    useEffect(() => {
      ref.current = value
    })
    return ref.current
  }

This custom Hook uses useRef to keep track of the previous state of the value that is getting passed into it.

The usePrevious Hook can then be used in other components such as the Counter component I mentioned above:

import { useState } from 'react'
import { usePrevious } from './usePrevious'

function Counter() {
  const [count, setCount] = useState(0)
  conts prevCount = usePrevious(count)

  return (
    <div className='counter'>
      <button onClick={() => setCount(count +1)}>Click me</button>
      <p>You clicked the button {count} times.</p>
      <p>Count before the last click: {prevCount}, current count: {count}</p>
    </div>
  )
}
export default Counter

A few points

Hooks are still experimental and their implementation will probably change in the future, so it's probably best not to rewrite all your code to use them yet. They are compatible with all your current components, so maybe give them a try when you create your next component.

Hooks should only be called at the top level of a React function component. Don’t call Hooks inside loops, conditions, or nested functions. This is to ensure that Hooks are getting called in the same order of every render and the state is correctly maintained.

Hooks are fully encapsulated — each time you call a Hook, it calls on isolated local state within the current component.

More React Hooks rules can be found in the React documentation.

Next steps

Check out the documentation for Hooks proposal to learn more about React hooks. The FAQ section will probably answer a lot of questions you may have as well. The React team also collects feedback.

Have you tried the new React Hooks feature yet? Feel free to leave a comment below.

Testing React and I18next with Jest

Sat, 20 Oct 2018 00:00:00 GMT

Testing React and I18next with Jest

In my last blog post I showed you how to use I18next within my React application. In this post I'd like to share how to test your components that contain strings generated with I18next. In my Photo Locations project I use Jest and Enzyme to test my code.

So first of all, if you haven't already, install Jest and Enzyme using either Yarn or npm. Follow the instructions in the Jest tutorial for React..

yarn add jest enzyme

Next in your main directory of your project, create a folder called __mocks__ because you won't actually want to use your live configuration for your tests. In the __mocks__ folder, create a file called react-i18next.js and copy the following code which can also be found in the I18next documentation into the file.

const React = require ('react');
const reactI18next = require ('react-i18next');

const hasChildren = node =>
  node && (node.children || (node.props && node.props.children));

const getChildren = node =>
  node && node.children ? node.children : node.props && node.props.children;

const renderNodes = reactNodes => {
  if (typeof reactNodes === 'string') {
    return reactNodes;
  }

  return Object.keys (reactNodes).map ((key, i) => {
    const child = reactNodes[key];
    const isElement = React.isValidElement (child);

    if (typeof child === 'string') {
      return child;
    }
    if (hasChildren (child)) {
      const inner = renderNodes (getChildren (child));
      return React.cloneElement (child, {...child.props, key: i}, inner);
    } else if (typeof child === 'object' && !isElement) {
      return Object.keys (child).reduce (
        (str, childKey) => `${str}${child[childKey]}`,
        ''
      );
    }

    return child;
  });
};

module.exports = {
  // this mock makes sure any components using the translate HoC receive the t function as a prop
  withNamespaces: () => Component => props => (
    <Component t={k => k} {...props} />
  ),
  Trans: ({children}) => renderNodes (children),
  NamespacesConsumer: ({children}) => children (k => k, {i18n: {}}),

  // mock if needed
  Interpolate: reactI18next.Interpolate,
  I18nextProvider: reactI18next.I18nextProvider,
  loadNamespaces: reactI18next.loadNamespaces,
  reactI18nextModule: reactI18next.reactI18nextModule,
  setDefaults: reactI18next.setDefaults,
  getDefaults: reactI18next.getDefaults,
  setI18n: reactI18next.setI18n,
  getI18n: reactI18next.getI18n,
};

Once that's done, it's time to create a folder called tests in the root directory of your project to start writing some tests.

For this blog, we will be testing that the h1 tag in my About.jsx component displays correctly. To do this, create a file called "About.test.js" inside the tests folder.

First import all the dependencies:

import React from 'react'
import { configure, shallow, mount } from 'enzyme'
import Adapter from 'enzyme-adapter-react-16'
import {About} from '../../../client/components/About'

Next create an adapter to be able to run Enzyme tests:

configure({adapter: new Adapter()})

Then you can start writing the actual test:

test('<About/> renders h1 component with given content', () => {
  const expected = 'About Photo Locations'
  const wrapper = shallow(<About t={(k) => 'About Photo Locations'} />)
  const actual = wrapper.find('h1').text()

  expect(actual).toEqual(expected)
})

The first line simply describes what the test is expected to do. Create the variable "expected" and give the text which is expected to appear in the About page header. Next shallow render the About component and pass it the text you want it to render, rather than calling up the json file and looking up the string. Then create a variable called actual to look up the text that is contained in the h1 tag. Last but not least compare the "expected" variable to the "actual" variable to ensure they match.

To find out more about the different rendering methods that Enzyme uses, such as shallow, mount or render, check out the Enzyme documentation.

To run the test, type:

jest about

into the console.

Something to watch out for

Because the mock react-i18next.js file contains the ES6 spread operator, which is not initially supported by Jest, I had to add:

yarn add @babel/plugin-syntax-object-rest-spread

I also upgraded Babel to version 7 to support this.

Have you tried writing tests for I18next with Jest yet? Feel free to share your experience in the comments section below.

Localisation in React with I18next

Sun, 07 Oct 2018 00:00:00 GMT

Localisation in React with I18next

Recently I participated in the pretty awesome Dev Academy Web Developer bootcamp to learn React and fullstack development and I enjoyed that immensely. I asked myself what's a good way to localise content in React applications? After some googling I came across i-18next and more specifically react-i18next.

I18next is an internationalisation framework and provides a lot of functionalities, such as pluralisation "out of the box". I thought I'd give it a try to see how easily it integrates with an existing application which I have been using to practise my React skills. The application is called Photo Locations and the code can be found on Github .

To get started, I used yarn to install the following packages:

yarn add react-i18next i18next i18next-browser-languagedetector i18next-xhr-backend

In my application I use webpack and I found the following package extremely helpful too:

yarn add -d @alienfast/i18next-loader

Next I added the following lines to the modules section my webpack config to configure i18next-loader:

{
  test: /locales/,
  loader: '@alienfast/i18next-loader',
  // options here
  //query: { overrides: [ '../node_modules/lib/locales' ] }
}

Once that was done, it was time to initialise i18next and to configure where I wanted to store my language string files. To do that I created an i18n.js file in my client directory.

import i18n from 'i18next'
import Backend from 'i18next-xhr-backend'
import LanguageDetector from 'i18next-browser-languagedetector'
import { reactI18nextModule } from 'react-i18next'

i18n
  .use(Backend)
  .use(LanguageDetector)
  .init({
    fallbackLng: 'en',

    // have a common namespace used around the full app
    ns: ['strings'],
    defaultNS: 'strings',

    debug: true,

    interpolation: {
      escapeValue: false,
    },

    react: {
      wait: true
    }
  })

export default i18n

In the file I specified that I am going to store my translations in a file named strings. It is good practise to use the same file name for all your languages and store them in differnt folders based on their locale or language code. That's what I did next.

To set up some text I created a folder called locales in my public folder which contains other static assets, such as images or CSS files. Within the locales folder I set up two languages for now, German (de) and my base language English (en).

In each language folder I then created a file called strings.json. All text will now be stored in these files in a simple json key:value structure. To make it easeier to see where my individual strings are being used, I created a json object for each individual component:

locales/en/strings.json

{
  "header": {
    "home": "Home",
    "about": "About",
    "contact": "Contact"
  },
  "contact": {
    "contact_header": "Get in touch!",
    "name": "Your name:",
    "email": "Your email:",
    "message": "Your message:",
    "send": "Send"
  }
}

locales/de/strings.json

{
  "header": {
    "home": "Start",
    "about": "Über",
    "contact": "Kontakt"
  },
  "contact": {
    "contact_header": "Schicke eine Nachricht",
    "name": "Dein Name:",
    "email": "Deine E-Mail:",
    "message": "Deine Nachricht:",
    "send": "Senden"
  }
}

As you can see in my two little examples above, both the English and the German json files contain the same keys on the left hand side, which I will be using to load the translations onto my pages from my components.

But before I could use the keys in the component, I had to import i18next into my index.js file and include it in the render method:

import i18n from './i18n'

document.addEventListener ('DOMContentLoaded', () => {
  render (
    <Provider store={store}>
      <I18nextProvider i18n={i18n}>
        <BrowserRouter>
          <App />
        </BrowserRouter>
      </I18nextProvider>
    </Provider>,
    document.getElementById ('app')
  )
})

Next I added "withNamespaces" to my App.jsx file and included it in the export, so other components have access to i18n via their props.

import { withNamespaces } from 'react-i18next'
class App extends React.Component {
  ...
}
export default withNamespaces('strings')(App)

Once that was done, I could call i18next from my components to actually display my content in both English and German. In my example here I'm looking at the Header.jsx file. First I imported I18n at the top of my file. Then I wrapped the content of my render section into an tag. Next I simply used {t('key.from.json.file')} wherever I had some text:

import { withNamespaces } from 'react-i18next'
import i18n from 'i18next'

class Header extends React.Component {
  constructor(props) {
    super(props)
    this.changeLanguage = this.changeLanguage.bind(this)
  }

  changeLanguage(language) {
    i18n.changeLanguage(language)
    this.props.setLanguage(language)
  }

  render() {
    let { t, i18n } = this.props
    return (
      <header>
        <nav className="navbar" role="navigation">
          <div className="logo header  header-left">
            <img src="/images/Logo.PNG" alt="Photo Locations" />
          </div>
          <div className="languages">
          <button className="button language" onClick={() => this.changeLanguage('de')}>{t('languages.de')}</button>
          <button className="button language" onClick={() => this.changeLanguage('en')}>{t('languages.en')}</button>
          </div>
          <div className="header">
            <Route exact path='/' component={Search} />
          </div>
          <div className="dropdown header">
            <button className="dropbtn" onClick={this.toggleVisibility}>
              <i className="fa fa-bars" aria-hidden="true"></i>
            </button>
            <div className="dropdown-content">
              <Link to="/">{t('header.home')}</Link>
              <Link to="/about">{t('header.about')}</Link>
              <Link to="/contact">{t('header.contact')}</Link>
            </div>
          </div>
        </nav>
      </header>
    )
  }
}

function mapDispatchToProps(dispatch) {
  return {
    setLanguage: (language) => {
      return dispatch(setLanguage(language))
    }
  }
}

export default withNamespaces('strings')(connect (null, mapDispatchToProps)(Header))

To quickly test the functionality of changing the language I added some buttons, which will be integrated into the menu later on. The full code can be found on Github .

All in all I just loved how straight forward it was to get going with I18n and I will certainly explore this component more as I'd love to be able to show off my newly learned React skills to my family in Germany as well.

Language Hierarchies

Thu, 13 Sep 2018 00:00:00 GMT

Language Hierarchies

When working with languages you will probably come across culture specific languages such as German spoken in Germany, German spoken in Austria or Swiss German. It makes sense to organise your translated files in such a way that your German speaking customers only ever see German. However, if you are missing translations for a specific software string, it is good practise to fall back to your default culture and not show your customers that a string is missing or not show them anything at all.

We can use language hierarchies to organise these fall-backs. But what's the best way to organise yourself?

Have a base language

At the top of language hierarchies you always have a base language. A base language is the language your company operates in or writes all their content in. You will always have strings available in this langauge and it is the source language for all your translations.

Keep translations neutral

Below the base language you have your culture neutral resource files. A neutral culture is associated with a language but not a country or region. For example French (fr) or German (de) are neutral language codes because they don't specify the country where the language is spoken in. It is best practise to store most of your translations in such a culture neutral file.

Then add some specifics

Of course you want to make sure that your translations read completely natural to your customers in all your target markets. So there will be country or region specific terms for some words. These should be stored in culture specific resource files. A specific culture is associated with a language and a country or region. For example German from Germany is de-DE, Canadian French is fr-CA, etc.

Organising your language resource files according to specificity and creating language hierarchies is a good way to ensure that you don't show any blank spaces or missing strings. It also means you don't need to store a huge amount of strings twice or more times for every single market.

Having read a bit about the theory, how do you organise language hierarchies? Feel free to share your thoughts in the comments section.

Machine translations

Wed, 08 Aug 2018 00:00:00 GMT

Machine translations

Almost everyone probably has heard of services such as Google Translate. Machine translation is the technical term for any computerised translation service. On a very basic level machine translation works by a simple substitution of words in one language for words in another. It is not quite an alternative to human translation yet as the following lines will show.

First serious attempts of automated or machine translation were made in the 1950s with rule based systems (RBTM), which combined a number of grammatical rules and dictionaries. The big wave of research occurred in the 1980s when an increased amount of content needing translation inspired statistical machine translation (SMT). This method is based on large volumes of analysed data for specific language combinations. Statistical machine translations were used by the German computer scientist Franz Joseph Och to develop Google translate in the early 2000s.

Since 2007, SMT and SMT-RBTM hybrids were used to build sophisticated translation platforms. One example is "Moses", a statistical machine translation system funded by the European Commission. The system was trained by passing it a collection of translated texts and once trained the system quickly found the highest-probability translation with the help of an efficient search algorithm. However, all of those systems still needed a lot of human editing.

Simultaneously, the industry developed less ambitious computer-assisted translation tools (CAT-tools), which can handle a lot of different file formats. These can also be combined with machine translation options. The translation memories and glossaries that these tools generate speed up the translation process enormously, especially for repetitive texts and updates and provide an easier terminology management and better quality control.

The newest development in terms of machine translation is neural machine translation (NMT) or deep neural machine translation. Like statistical machine translation, the system starts by learning from a variety of translated texts but the difference is that this learning happens largely without human intervention through artificial intelligence. Simple neural networks simply take the same input and turn it into the same output every single time. Recurrent neural networks do this a bit more cleverly. They do not only take the input itself but also take into account the input around the actual input, which will result in much more accurate translations.

Example:

German original:	Sollten sich Unklarheiten betreffend der Auslegung einer oder mehrerer der nachstehenden Vertragsbestimmungen ergeben, gilt im Zweifel die für den Auftraggeber günstigere Auslegung.
SMT translation:	Should ambiguities concerning the interpretation of one or more of the following provisions of the Treaty, is in doubt for the customer more favorable interpretation.
NMT translation:	In the event of any uncertainties concerning the interpretation of one or more of the following provisions of the contract, the interpretation which is more favorable to the contracting entity shall apply.

It appears that neural machine translation copes much better with syntax and produces a much more natural output. This is due to the fact that the system is able to translate the semantic meaning of entire phrases rather than translating word by word.

At first sight this makes post-editing a much simpler process and means it is actually post-editing rather than a complete re-translation. However, this is still in early phases of testing and neural machine translation still only processes one sentence at the time, which can lead to errors in ambiguous phrases, where human translators would take the wider context into account:

Example:

1st sentence:	The water was cold and the current strong. I went to the bank. My feet sunk into the mud.
NMT translation:	Das Wasser war kalt und die Strömung stark, als ich zur Bank ging. Meine Füße versanken im Schlamm.

2nd sentence:	I had run out of cash. I went to the bank. It had just closed.
NMT translation:	Ich hatte kein Bargeld mehr, also ging ich zur Bank, aber sie hatte geschlossen.

In both of these sentences, neural machine translation renders the English word “bank” as “Bank” in German, i. e. the financial institution. It did not identify the alternative meaning, i.e. river bank. Also, the pronoun “it” in the second sentence is translated as “es” (neutral) when it should be “sie” (feminine because “Bank” in German is feminine).

However, just by changing the first example a little bit, we can illustrate the strength of neural machine translation compared to statistical machine translation because it can accommodate the semantic qualities of words within a sentence: 1st sentence: The water was cold and the current strong, when I went to the bank. My feet sunk into the mud. NMT translation: Ich hatte kein Bargeld mehr, also ging ich zur Bank, aber sie hatte gerade geschlossen.

This time the neural machine translation chose the correct pronoun.

Neural machine translation is still in its infancy and there are things which are not generally understood just yet. One example is that NMT sometimes leaves out whole chunks of text for no apparent reasons. Another issue for language service providers to consider is data security, since most neural machine translation systems generally run in the cloud. However, some systems, such as SDL Trados 2017 already incorporate this technology via an API and one certainty is that we should keep an eye on this rapidly developing technology.

Glossaries and translation memories

Mon, 11 Jun 2018 00:00:00 GMT

Glossaries and translation memories

Glossaries

A glossary is a list of standardised terms in the source language of a company.

Translation glossaries ensure consistency and clarity in all translated materials by helping eliminate uncertainty. No matter what product you are working on, it pays to create a list of all the important terms. These terms should then be used consistently by all translators and reviewers.

Here are a few points to consider when creating a glossary:

Structure the glossary with purpose Include only terms specific to the company or the product Make the glossary translator-centric and provide as much context as possible Complex terms should be listed with a definition and context If you are creating multi-lingual glossaries, conduct an in-country review before using the glossary Translation glossaries exist because even the best linguists may have difficulties translating key marketing concepts or catch phrases. They give a great resource and make their job easier.

Things you might want to include in a glossary:

Key terms: A good glossary should provide a thorough list of relevant key terms that are very specific to the subject matter or the company’s culture.

Definitions: These key terms should be clearly defined, so that linguists understand them clearly.

Preferred translations: Add your company’s preferred translations for terms in the glossary. This will help linguists with the accuracy and consistency of word choices in the translation.

Terms that should not be translated: Some products, services, or proper names may need to be left in the source language. Include those, so there is no uncertainty whether or not such a term should be translated.

A glossary is a living document, and you have to keep building it over time. Whenever a new key term is identified, make sure you add it to the glossary.

Translation memories

A translation memory or TM for short is a database that contains human translations. They are an integral part of the translation process as the speed up translation, maintain consistency and save cost.

This database stores previously translated segments, which depending on the type of translation, can be sentences, paragraphs, single words, etc.

When language service providers carry out word counts to provide you with quotes, they will search this database for previous translations similar to what you are sending them and they then adjust their charges accordingly. So if a sentence has been translated in full previously, it is a 100% match and they will only charge you a minimal fee for handling or sometimes no fee at all. If it is a partial match, then the charge may just be 75% or 50% of the normal full charge.

The most common format for translation memories is .tmx. TMX stands for translation memory eXchange. It is a bilingual xml file that provides a standard method to describe translation memory data that is being exchanged amongst tools and / or translation vendors.

Localisation - The very basics

Mon, 21 May 2018 00:00:00 GMT

Localisation - The very basics

I have worked in software localisation for a good few years now and often I find myself googling and collecting information and how to’s on various topics related to localisation and I thought, rather than keeping it all hidden in my little notebook, I will summarise things I research and collate them in this blog.

Localisation is often abbreviated to L10N, which simply takes the first and the last letter of the word itself, plus the count of letters of the word in between these letters.

It is the provision of service for the linguistic and cultural adaption of products to the requirement of a market. What exactly does that mean? Translating is just one little part of localisation. Translation is the process of converting written text from one language to another. It requires that the full meaning of the source material be accurately rendered into the target language. Special attention needs to be paid to nuance and style.

As part of localistion, time, date and number formats need to be adapted, the correct currencies and payment methods need to be used. In some cases images and colours need to be adapted as well as some colours may have different connotations in different cultures.

In comparison what is internationalisation? Internationalisation can also be abbreviated in a similar fashion: I16N. It is the process of generalising a product in such a way that it can be adapted in various languages and cultural conventions without having to redesign the product every single time you would like to publish it in another market.

Another term worth mentioning is globalisation. Globalisation addresses business issues of taking a product to a global market. In terms of websites, globalisation refers to enabling that website to deal with non-English speaking visitors, i.e. internationalising the website’s back-end, designing a multilingual architecture (e.g. ensure that your databases can deal with special characters) and localising the website’s static or dynamic content.

	import Vue from 'vue'
	import i18next from 'i18next'
	import VueI18Next from '@panter/vue-i18next'
	import App from './App.vue'
	import en from './locales/en.json'
	import de from './locales/de.json'

	const locales = {
	en: en,
	de: de
	}

	Vue.use(VueI18Next)

	i18next.init({
	lng: 'en',
	fallbackLng: 'en',
	resources: {
	en: { translation: locales.en },
	de: { translation: locales.de }
	}
	})

	const i18n = new VueI18Next(i18next)

	if (document.getElementById('app')) {
	/* eslint-disable-next-line no-new */
	new Vue({
	el: '#app',
	i18n: i18n,
	render: h => h(App)
	})
	}

	{
	"message": "hello",
	"tryitfree": "Try it free",
	"readytobuild": "Ready to build your community?"
	}

	{
	"message": "hallo",
	"tryitfree": "Probiere es kostenlos",
	"readytobuild": "Bist du bereit, deine Community aufzubauen?"
	}