10. Localizing Your Application¶

Introduction¶

Because Mojito is built with YUI, which has an internationalization utility, localizing Mojito applications is fairly straightforward and easy. In this module, we’re just going to localize the title of our dashboard to show you how you would localize your own applications. In a nutshell, you provide localized strings, Mojito determines the language environment of the client, and you apply the correct localized string with an addon from your controller.

Final Product¶

In the screenshot, you can see that our dashboard has three localized pages: English, simplified Chinese, and Spanish. Our application only localizes the title of the page, but more importantly, you’ll learn how to localize your own applications in the future.

Lesson: Localizing Applications¶

Mojito lets you localize applications by detecting the language environment of the client environment and then using the the YUI Internationalization utility to dynamically retrieve localized strings. Although Mojito does the work of detecting the language environment of the client, your application still needs resource bundles that contain localized strings and the Intl addon, which uses the YUI Internalization utility to fetch the correct localized string. The YUI Internationalization utility uses the Intl.lookupBestLang method to determine the best language based on an application’s request and a module’s language support.

We’re going to first look at the resource bundle files and then show how to use the Intl addon to access the localized strings in those files.

YUI.add('lang/PageLayout_zh-Hans.js'), function(Y) {
  ...
}, "3.1.0", {requires: ['intl']});

Y.Intl.add(
  "PageLayout",  // associated module
  "zh-Hans",    // BCP 47 language tag
  // key-value pairs for this module and language
  {
    YUITitle: "Trib - YUI 开发人员仪表板",
    MojitoTitle: "Trib - Mojito 开发人员仪表板"
  }
);

}, "3.1.0", {requires: ['intl']});

YUI.add("lang/FrameMojit_zh-Hans", function (Y) {
  Y.Intl.add(
    "FrameMojit",  // associated module
    "zh-Hans",    // BCP 47 language tag
    // key-value pairs for this module and language
    {
      YUITitle: "Trib - YUI 开发人员仪表板",
      MojitoTitle: "Trib - Mojito 开发人员仪表板"
    }
  );
}, "3.1.0", {requires: ['intl']});

...
  index: function (ac) {
    var view_type = ac.params.getFromRoute('view_type') || "yui";
    if (view_type === "yui") {
      ac.composite.done({
        title: ac.intl.lang("YUITitle"),
        button_text: "See Mojito Dashboard",
        other: "/mojito"
      });
    } else if (view_type === "mojito") {
      ac.composite.done({
        title: ac.intl.lang("MojitoTitle"),
        button_text: "See YUI Dashboard",
        other: "/"
      });
    }
  }
...

Creating the Application¶

1. After you have copied the application that you made in the last module (see Setting Up), change into the application 10_localization.

2. First let’s add the lang directory to the PageLayout mojit.

3. In the lang directory, create the language resource bundle files PageLayout_en-US.js, PageLayout_es-419.js, and PageLayout_zh-Hans.js with the content below. Notice that the YUI registered name is the same as the directory and file, the inclusion of the intl module, and the registration of the language bundle with Y.Intl.add.

   PageLayout_en-US.js

   YUI.add("lang/PageLayout_en-US", function (Y) {
     Y.Intl.add(
       "PageLayout",  // associated module
       "en-US",    // BCP 47 language tag
       // key-value pairs for this module and language
       {
         YUITitle: "Trib - YUI Developer Dashboard",
         MojitoTitle: "Trib - Mojito Developer Dashboard"
       }
     );
   }, "3.1.0", {requires: ['intl']});
   

   PageLayout_es-419.js

   YUI.add("lang/PageLayout_es-419", function (Y) {
     Y.Intl.add(
       "PageLayout",  // associated module
       "es-419",    // BCP 47 language tag
       // key-value pairs for this module and language
       {
         YUITitle: "Trib - YUI Panel para desarrolladores",
         MojitoTitle: "Trib - Mojito Panel para desarrolladores"
       }
     );
   }, "3.1.0", {requires: ['intl']});
   

   PageLayout_zh-Hans.js

    YUI.add("lang/PageLayout_zh-Hans", function (Y) {
      Y.Intl.add(
       "PageLayout",  // associated module
       "zh-Hans",    // BCP 47 language tag
       // key-value pairs for this module and language
       {
         YUITitle: "Trib - YUI 开发人员仪表板",
         MojitoTitle: "Trib - Mojito 开发人员仪表板"
       }
     );
   }, "3.1.0", {requires: ['intl']});
   

4. The controller of the PageLayout mojit will use the Intl addon to access the values of the registered language bundlers. Update the index method of the controller with the following:

   index: function(ac) {
     // Register helper for use in template
     ac.helpers.expose('linker', createLink);
   
     var view_type = ac.params.getFromRoute('view_type') || "yui";
     if (view_type === "yui") {
       ac.composite.done({
         title: ac.intl.lang("YUITitle"),
         button_text: "See Mojito Dashboard",
         other: "/mojito"
       });
     } else if (view_type === "mojito") {
       ac.composite.done({
         title: ac.intl.lang("MojitoTitle"),
         button_text: "See YUI Dashboard",
         other: "/"
       });
     }
   }
   

5. Also, require the Intl addon by adding the string mojito-intl-addon to the requires array.

6. Since this is our final application, let’s put a little polish on the presentation with background images, favicons, and CSS. Copy the following images to the specified location:

   • /assets/favicon.ico to 10_localization/assets/
   • /assets/images/dust.png to 10_localization/assets/images/
   • /mojits/Blog/assets/favicon.ico to 10_localization/mojits/Blog/assets/
   • /mojits/Blog/assets/favicon-blog.png to 10_localization/mojits/Blog/assets/
   • /mojits/Calendar/assets/favicon-calendar.ico to 10_localization//mojits/Calendar/assets
   • /mojits/Calendar/assets/favicon-calendar.png to 10_localization//mojits/Calendar/assets
   • /mojits/Twitter/assets/favicon.ico to 10_localization/mojits/Twitter/assets/
   • /mojits/Twitter/assets/favicon-twitter.png to 10_localization/mojits/Twitter/assets/
   • /mojits/Gallery/assets/favicon-blog.png to 10_localization/mojits/Gallery/assets/
   • /mojits/Github/assets/favicon-github.png to 10_localization/mojits/Github/assets/

7. We’re going to update the CSS for some mojits as well so that the images and styles are used. Add the code to the file /mojits/Blog/assets/index.css:

   #blog h3 strong {
     background-image: url(/static/Blog/assets/favicon-blog.png);
   }
   

8. For the following CSS files, just replace the content with the code below:

   /mojits/Calendar/assets/index.css

   #calendar h3 strong {
     background-image: url(/static/Calendar/assets/favicon-calendar.png);
   }
   #calendar .inner li {
     white-space: nowrap;
     text-overflow: ellipsis;
     overflow: hidden;
   }
   #calendar .inner li span {
     padding-right: 4px;
     font-size: .8em;
     display: inline-block;
     width: 106px;
     max-width: 7.6 em;
     overflow: hidden;
   }
   

   /mojits/Gallery/assets/index.css

   #gallery h3 strong {
     background-image: url(/static/Gallery/assets/favicon-blog.png);
   }
   

   /mojits/Github/assets/index.css

   #github h3 strong {
     background-image: url(/static/Github/assets/favicon-github.png);
   }
   

   /mojits/Twitter/assets/index.css

   #twitter h3 strong {
     background-image: url(/static/Twitter/assets/favicon-twitter.png);
   }
   

9. Launch your application to see the application in its more finished form.

10. To view the localized title in Chinese for the dashboard, add the query string parameter ?lang=zh-Hans to the URL and refresh the page. You can see the title in Spanish as well with the query string parameter ?lang=es-419.

11. Let’s add a functional test to test for a localized title as well. Create the test file arrow_tests/test_zh-Hans_title.js with the following content:

    YUI({
      useConsoleOutput: true,
      useBrowserConsole: true,
      logInclude: { TestRunner: true }
      }).use('node', 'node-event-simulate', 'test', 'console', function (Y) {
    
      'use strict';
      var suite = new Y.Test.Suite("TribApp: Localization Test"),
          url = window.location.protocol + "//" + window.location.host + "/";
      suite.add(new Y.Test.Case({
        "test localized title": function () {
          Y.Assert.areEqual("Trib - YUI 开发人员仪表板", Y.one('body h1').get('innerHTML'));
        }
      }));
      Y.Test.Runner.add(suite);
    });
    

12. Add the test scenario below after the first scenario specified in the scenario array in the test descriptor as well.

13. Go ahead and run the functional tests again. You should see an additional test case passing.

14. Congratulations, you have completed all of the modules in this tutorial. There is still more to learn about Mojito, but you should have a strong grasp of the basics that you can build on. If you haven’t already, be sure to read the documentation and work through the code examples.

Summary¶

Our topic was a bit more focused in this module. We added localization support for three languages for the application heading using the Intl addon and resource bundles. To do this we had to learn the following:

• creating resource bundles
• adding the Intl addon to our controller
• using the Intl addon to access the localized strings in the resource bundles

Troubleshooting¶

Q&A¶

• Can you create a global resource bundle that all mojits can use?

  No, the resource bundle has to be associated with a YUI module. Each mojit is registered as a YUI module that can then be associated with a resource bundle.

• Can the Intl addon format dates for a given language environment?

  Yes, although we didn’t use it in our application, the Intl addon has the method formatData that will format dates for you. Again, Mojito is relying on YUI (the YUI module datatype-date) to do this for you.

Test Yourself¶

Terms¶

• BCP 47 language tags
• resource bundle - Files that provide resources to YUI modules. In the case of localization, we are using language resource bundles that associates a BCP 47 language tag and localized strings to the YUI module that can access it.

Source Code¶

10_localization trib

Further Reading¶

• Internationalization
• Internationalizing Your Application