-
Notifications
You must be signed in to change notification settings - Fork 9
I18n Translations
The way in which translations work for Bike!Bike! is somewhat unique. This document describes how translations should work, if the current implementation does not match this document a ticket will need to be filed.
Translations are meant to to be collaborative; any user with permission can edit any translation from the site.
en.bikebike.org is English, es.bikebike.org is Spanish, de.bikebike.org is German, etc. The site should try to detect the user's language and redirect to the appropriate URL. For development purposes, localhost and dev.bikebike.org should default to English. It is important for SEO purposes that on the live site there should be only one URL for each language, http://bikebike.org or http://www.bikebike.org should be redirected to the user's language.
The only other way in which English is treated any different than any other language is in that translations can be provided with an English default. Other than that, all English translations can be edited just like any other language, thankfully taking the task of copy writing to those who excel in it, instead of those that don't (often developers).
When the code tries to translate a key, it first looks in .translation-cache.yml, if the translation is not there it will then look in the database. If it is found in the database it caches it in .translation-cache.yml. If it is still not found, default text is displayed which can be default English text provided by the developer, some random Lorem Ipsum, or the last section of the key (user.form.save = 'save' for example).
When a translation is entered by a user, the translation is saved in the database. When tests are executed, the new translations are picked up and put into translation-info.yml so that they can be check in and merged with other developers changes. After pulling new code, to get the new translations can be put into the database using the task:
rake translations:migrate
The date that a key was translated should also be provided, thus only translations with a newer translation date should be migrated when running this task.
Translations and automated testing go hand in hand. When a full test suite is executed, the tests record every translation, on which page it occurred and what the translation is. This data is then used to build the page used to display and edit all translations. If tests aren't run or don't cover enough code, translations will fail to appear on the page thus causing serious problems for the live site. This should be enough incentive to force most developers to properly test their code.
Learn more about testing practices.
When a translation is missing, the user should be provided with a fallback (most likely English) but they should also know that they are seeing another language other than their own.
All relevant text should also be available to be translated. For example, this would include organization and workshop descriptions as well as workshop titles, but not organization titles.
There should be absolutely no English text provided in HTML, HAML, or Javascript code ever. All copy should go through the _ (underscore) method.
The underscore method can take the following parameters:
A string in the format of page_or_method.section.name_or_title. This can really be any string but keys should be consistent so that they can be reused as often as possible, creating less work for the translators. When no default text is provided and a translation is missing, the method will return the the string after the last period with underscores replaced by spaces, 'name or title' in the example above.
This can be a symbol or a string which describes what kind of text should be displayed and if the translation is missing, random lorem ipsum will be provided instead. If a string (which doe not match any of the strings below) if provided, the output will be that string if the translation is missing. Possible values are:
If one of these values is provided a single character or the number provided in behavior_size is returned.
A single word or behavior_size words.
A single sentence or behavior_size sentences.
Ten sentences or behavior_size paragraphs ten sentences long.
A single sentence with every first character of every word capitalized.
If the string does not match any of the above, the string itself is returned, allowing for default text to be provided.
A number that describes how large the above should be, for example, 2 paragraphs, 3 words, etc. This defaults to 1 and when default text is provided the value is ignored.
This is a strong parameter. A hash map of variable names and values to be available to the translation. For example {:username @user.name}. These variable names will be provided to the translators and they will be able to enter the name where required using the syntax %{variable_name} (%{username} in this example).
In your HAML files you can simply write =_'key',parameters....
| Input | Example Output (when translation does not exist) |
|---|---|
_'forms.Submit' |
Submit |
_'home_page.welcome_message',:p |
Cras risus ipsum, faucibus ut, ullamcorper id, varius ac, leo. Suspendisse faucibus, nunc et pellentesque egestas, lacus ante convallis tellus, vitae iaculis lacus elit id tortor. Praesent porttitor, nulla vitae posuere iaculis, arcu nisl dignissim dolor, a pretium mi sem ut ipsum. Vivamus euismod mauris. Vivamus laoreet. |
_'home_page.page_title',:t |
Etiam Ut Purus |
_'home_page.page_title', 'words', 4 |
Proin faucibus arcu quis |
_'navigation.organizations.title','Organizations' |
Organizations |
_'forms.country.placeholder','Select a Country' |
Select a Country |
_'home_page.welcome_user',vars: {username: @user.user} |
welcome user |
_'home_page.welcome_user',"Welcome #{@user.name}",vars: {username: @user.user} |
Welcome Gerald |