Localization is a way to introduce additional languages into your web development projects. This article is part one of a three part series around localizing your application in Ember. See How Ember Helps Localize Your Project and Shorter Days: A Case for Visual Testing in Localization to continue reading about localization.
A localization string is any string of copy/content within your app or view that a person will read visually or with assistive technology. What makes a localization string different from any other copy or content is that the text is made available for translation into other languages.
Establish Project Pattern
To create a localization string, we start by establishing an easy to follow pattern for all localization keys in the project. A localization key is a reference used in place of copy/content within our template file and connected to a separate language file in the project.
To help understand how the localization key is constructed, let’s look at the Ember file structure. Within our Ember app, a demo app called Imatic, we have an app/templates directory and a translations directory.
imatic/
├── app/
| ├── templates/
| ├── contact-form.hbs
├── translations/
| ├── en-US.yaml
| ├── es-ES.yaml
Here is an example of our localization key pattern:
app-name.template-name.component-name.string-name
Each period-separated name is tied to a place in the file structure or within the Handlebars template.
Let’s break those down:
app-name is the name of our app or project, in this case “imatic”
template-name is the name of the template file, “contact-form”
component-name is the name of the individual page component, “contact-form-container”
string-name is the name of the content of the string, “submit-button”
With this pattern, our entire project can easily create localization keys that provide context as to where the string is found within our code.
Constructing Localization Keys
Now that we have an understanding of the structure of our project and our localization key project pattern, we can create keys for our strings. Based on the pattern and file structure shown above, the following key is what we will use in our project.
imatic.contact-form.contact-form-container.submit-button
Using the Localization Key
To use our new localization key, within our app/templates/contact-form.hbs file we will replace the string with our localization key:
Before localization
<button>Submit Contact Form</button>
After localization
<button>
{{t "imatic.contact-form.contact-form-container.submit-button"}}
</button>
The t within the Handlebar curly braces is from ember-intl and represents a helper than connects the key "imatic.templates.contact-form.submit-button" to its string, “Submit Contact Form”. This will allow the Ember application to use other languages defined in the /translations folder.
Adding Translations
The localization key and localization string are connected within each of the individual translation files for the languages needed. For this project, we will need English and Spanish (Spain). Therefore, we will have two translation files within the translations folder: translations/en-US.yaml and translations/es-ES.yaml.
en-US.yaml
imatic:
contact-us:
contact-modal:
submit-button: Submit contact form
es-ES.yaml
imatic:
contact-us:
contact-modal:
submit-button: Enviar formulario de contacto
Now that the Ember template file contains the ember-intl t helper with the localization key and the yaml files contain the translations for each language, our string can be translated!
This is an example of what each button would look like in each language:
DockYard is a digital product agency offering custom software, mobile, and web application development consulting. We provide exceptional professional services in strategy, user experience, design, and full stack engineering using Ember.js, React.js, Ruby, and Elixir. With a nationwide staff, we’ve got consultants in key markets across the U.S., including Seattle, San Francisco, Denver, Chicago, Dallas, Atlanta, and New York.
