Internationalization (i18n) in Your App

Use Unicode

Yahoo! Mail is based on Unicode and applications must be based on it too. HTML, CSS, JavaScript, and other source files must be encoded in UTF-8. Text data is exchanged in UTF-8. Applications must be designed so they can transmit, process, and store text using characters at least from the entire Basic Multilingual Plane of Unicode, better from the entire Unicode character set.

Files must use the appropriate encoding identification:

HTML: <meta http-equiv="content-type" content="text/html; charset=utf-8"> as the first subelement of the <head> element.
CSS: @charset "utf-8"; as the first characters of the file.
JavaScript: charset="UTF-8" as an attribute of every <script> element referring to the JavaScript file.

Yahoo! Mail serves all application assets with the charset=utf-8 parameter set on the Content-Type header.

Communication via openmail.Application.callWebService or via XMLHttpRequest must use UTF-8. Text that's part of the path or query string of the request URI must be encoded using encodeURIComponent() (callWebService handles this for parameters provided in the parameters object; YAHOO.util.Connect.setForm for parameters provided in the form object). Browsers by default use UTF-8 to encode the request body – don't change this. Set the charset=utf-8 parameter on the request Content-Type header. On the server handling the request, decode request URI and request body using UTF-8. When generating a response in any form of text (including JSON and XML), use UTF-8, and set the charset=utf-8 parameter on the response Content-Type header (RFC 4627 doesn't seem to allow this for type application/json, but it's necessary for some browsers).

Add Language-Specific Legal Content

In your application's config.xml, you can specify Internationalized content. You can give "Name" , "Description" , "Developer Name", "Terms of Service", "Privacy Policy" and "Landing page" specific to every Intl. Following is an example of config.xml with internationalized content.

<?xml version="1.0"?>
<openmail_app_config version="0">
  <name>Hello World (i18n)</name>
  <description>Hello World, internationalized version</description>
  <data/>
  <events>
    <click>
      <action>
        <launch>
          <view>main</view>
          <target_zone>tab</target_zone>
        </launch>
      </action>
    </click>
  </events>
  <intl_values>
    <intl_strings intl="en-AU">
      <name>Hello World</name>
      <description>Hello World, internationalized Version (en-AU)</description>
      <developer_name>Yahoo!</developer_name>
      <legal>
          <terms_of_service url="http://developer.yahoo.com/terms/"/>
          <privacy_policy url="http://info.yahoo.com/privacy/us/yahoo/devel/details.html"/>
          <landing_page url="http://developer.yahoo.com/"/>
      </legal>
    </intl_strings>
    <intl_strings intl="fr-FR">
      <name>Bonjour monde</name>
      <description>Bonjour monde, version internationalisée (fr-FR)</description>
    </intl_strings>
  </intl_values>
</openmail_app_config>

<?xml version="1.0"?>
<openmail_app_config version="0">
  <name>Hello World (i18n)</name>
  <description>Hello World, internationalized version</description>
  <data/>
  <events>
    <click>
      <action>
        <launch>
          <view>main</view>
          <target_zone>tab</target_zone>
        </launch>
      </action>
    </click>
  </events>
  <intl_values>
    <intl_strings intl="en-AU">
      <name>Hello World</name>
      <description>Hello World, internationalized Version (en-AU)</description>
      <developer_name>Yahoo!</developer_name>
      <legal>
          <terms_of_service url="http://developer.yahoo.com/terms/"/>
          <privacy_policy url="http://info.yahoo.com/privacy/us/yahoo/devel/details.html"/>
          <landing_page url="http://developer.yahoo.com/"/>
      </legal>
    </intl_strings>
    <intl_strings intl="fr-FR">
      <name>Bonjour monde</name>
      <description>Bonjour monde, version internationalisée (fr-FR)</description>
    </intl_strings>
  </intl_values>
</openmail_app_config>

<?xml version="1.0"?>
<openmail_app_config version="0">
  <name>Hello World (i18n)</name>
  <description>Hello World, internationalized version</description>
  <data/>
  <events>
    <click>
      <action>
        <launch>
          <view>main</view>
          <target_zone>tab</target_zone>
        </launch>
      </action>
    </click>
  </events>
  <intl_values>
    <intl_strings intl="en-AU">
      <name>Hello World</name>
      <description>Hello World, internationalized Version (en-AU)</description>
      <developer_name>Yahoo!</developer_name>
      <legal>
          <terms_of_service url="http://developer.yahoo.com/terms/"/>
          <privacy_policy url="http://info.yahoo.com/privacy/us/yahoo/devel/details.html"/>
          <landing_page url="http://developer.yahoo.com/"/>
      </legal>
    </intl_strings>
    <intl_strings intl="fr-FR">
      <name>Bonjour monde</name>
      <description>Bonjour monde, version internationalisée (fr-FR)</description>
    </intl_strings>
  </intl_values>
</openmail_app_config>

Externalize Language Dependent Content

In order to facilitate localization, applications should separate all language dependent content from the language independent core of the application. Typically, the bulk of the language dependent content are user interface strings that need to be translated, but there may also be style properties such as font sizes (which often have to be increased for East-Asian languages) or URLs to pages that exist in different languages.

We recommend the use of two file formats:

For editing and translation, we recommend the Yahoo! Resource Bundle YRB format, with a .pres suffix. This format is similar to Java resource bundles, but fully UTF-8 based. It is preferred as a source format because it's easier to edit and allows for comments, which can provide important information to translators.
For uploading via ymdt and for loading at runtime, JSON files are used, with a .json suffix. This format is well supported in JavaScript libraries.

For the conversion from YRB format to JSON format, you can use the simple converter located here.

Files containing localized content come in families with a common base name: A root file contains a default version of the content that's accessible to the largest possible set of users, e.g., by using a popular language such as Simplified Chinese or English. Additional files include an RFC 5646 language tag identifying the language of the content. For example, using the base name "resources":

resources.pres or resources.json – root file.
resources_en-AU.pres or resources_en-AU.json – file for English as used in Australia.
resources_zh-Hant-TW.pres or resources_zh-Hant-TW.json – file for traditional Chinese as used in Taiwan.

Once you have uploaded uploaded the .json files as assets, applications can use Y.io to load the .json file and apply them to the DOM as demonstrated in the internationalized Hello World Sample App.

Use Complete Sentence Patterns

In order to allow translations to use correct grammar, externalized strings should always include the complete sentence or phrase to be displayed, never fragments that will be concatenated. Where runtime values have to be inserted, parameters should be used with the Y.Lang.sub method as demonstrated in the internationalized Hello World Sample App.