Rules to Better Internationalization


Hold on a second! How would you like to view this content?
Just the title! A brief blurb! Gimme everything!
  1. Do you know why you should Chinafy your app?


    China is a booming market and now is the time to take advantage of this growing user base. If you have a successful application you should bring it to the Chinese market.

    Most Chinese consumers will not make a purchase or use your application if information is not easily available in Chinese.


    ​You can grow and target your audience better using the local social media networks

    You should ensure your application works in China, and that critical application resources are not blocked by the firewall

    You should integrate with local services (such as video streaming)

    Localizing for the market is not just translation​

  2. Do you know how to better localize your application?

    ​​​​​Localization makes your web application ready to work more than one language — and it’s much easier if you do it from the beginning. Just follow these tips to better localize your application for a specific country or region.​

    Figure: SSW LinkAuditor application is available in Chine​​se. 
  3. Do you set your application default language to automatically change to local language?

    If you are localizing your web application to make it available in a varitety of languages, it's better to ​set your application default language to automatically change to local language. e.g. Make the web application default language as same as the browser language.

    ​In order to use your web application in your preferred language, simply set that language in your browser, save/apply the new settings and then launch your application. 


    Figure: Detect your users language preference and display in that language​. ​


  4. Do you always give the user an option to change the locale?

    Localization because absolutely needed when  your application has to be shown to people in many countries. To make your application more friendly, it's very important to always give the user a option to change the locale (e.g. by adding locale dropdown menu on page) and remember this choice for the future visits. e.g. To change the language for your application, you can simply choose the new language from the language dropdown.

    Facebook Like pages
    Figure: Give the user an option to change the locale. ​
  5. Do you use client-side tools for localization as much as possible?

    With the increasing use of JavaScript on the client and HTML5, client-side localization is fast becoming a necessity for displaying messages, text, and resources localized for the user's culture. You can use client-side tools for localization as much as possible so that for the most part, the back end of your service remains unchanged. e.g. If you are using AngularJS, then use the Angular Translate plugin.

    Figure: Using Angular Translate plugin for localization. ​
  6. Do you provide numerous comments in application resources that define context?

    ​​Knowing the context and use of certain strings will help translators choose the right translation from the beginning when you localize your web application to make it available in a variety of languages. Most translation tools will allow translators to see these comments as they translate the strings. To make your comments more friendly, it's better to list in the comment field where this text is used. e.g.

    • ​Text
    • Validation
    • Tooltip
    • Textbox Placeholder​​
    Figure: Use the comment field in the resx to tell you where it is used.​
  7. Do you follow a 'Definition of Implementing Social Media Campaigns'?

    Promoting your application and business via social media can be extremely beneficial, not only for promoting of a business, but for feedback from customers as well. To help implement social media campaigns, try these tips:

    • Target platforms for the countries in which you’ll have either an e-commerce or on-the-ground presence. e.g. Facebook/Qzone, Twitter/Weibo.
    • Understand the specific social media websites and to craft the message for each  language. Always localize, don’t just translate. Google translate just isn't good enough, always give it to a native speaker to translate. 
    • Don't make the text longer than what the shortest supported is (usually Twitter which is 140 characters).
    • Studies show that posts with an image get more traction .
    • Post it to the English site.
    • Then post it to the Chinese site.
    • Great, now you are ready to post to all of the social media platforms simultaneously.
    • Facebook Like pages
      Figure:  Make sure that your social media presence covers the countries you have translated your application into
                    e.g. Link Auditor on Weibo (A local social media, China’s Twitter replacement).  

    We have a service called SSW Chinafy that can help you get started following this rule.

  8. Chinafy - Do you manage 3rd party dependencies?

    Modern websites can use 3rd party dependencies from many different sources. This can include js and CSS libraries from CDNs, video providers such as YouTube and other 3rd party APIs.

    Many of these services are completely blocked inside other countries. China, in particular, currently blocks all the below:

    • Facebook​
    • Google
    • YouTube
    • Vimeo
    • Twitter

    Although China is the most well-known country for blocking sites, other countries also block services - like Google (e.g. Iran, Syria) and YouTube (e.g. Pakistan, Syria).

    Figure: Blocked sites as per​

    If the runtime operation of your site depends upon these services, your website will either fail or perform poorly for users in China. Start by reviewing how many of these services are essential, what they do and whether there are China-based equivalents. The fewer external dependencies in your site, the easier it will be to Chinafy.

    Every attempted request to a blocked service can add serious delays to your site's performance as each one can take ​over a minute to timeout. When loading a page, browsers have a limit on the number of simultaneous connections they will open. Google Chrome, for example, will support 6 connections to one domain and 10 connections overall. If all those connections get used attempting to connect to blocked resources, the entire page loading process can stall for minutes!

    To measure the impact of this, you need to be able to browse the website from inside China. From there you can open the site and collect performance measurements from the network tab of your browser's dev tools.

    Figure: Bad example: This browser in China was stalled attempting to load resources from Facebook, Google, and YouTube.

    This situation can first be improved by finding and removing unnecessary dependencies.  Next, ensure that all required CSS and JavaScript content can be loaded - by either hosting within your site or using a CDN that is available from China.

    Finally, you may find that there are features you still want to use elsewhere but need to disable for users in China. In this case, we recommend detecting the available services from the client. For more information read: Do you detect available services? 

  9. Do you add multilingual support (Angular)?

    How to realize multilingual support in an Angular project?

    There are several ways of implementing multilingual support in an Angular project, the following libraries are popularly used:
    Internationalization (i18n): the standard Angular built-in module to help the application dealing with multilingual. It creates multiple language versions of your application.
    ngx-translate: a library enhanced the Angular built-in feature, it supports not only template translations but also can be used in the code by APIs. 
    angular-gettext:  the simplest powerful 3rd party library provides the translation support to Angular.
    The following table shows the pros and cons of the 3 libraries:


    Pros (+)

    Cons (-)



    • Better support of displaying dates, number, percentages, and currencies in a local format.
    • Better support of handling plural forms of words, and alternative text.
    • It only works with one language at a time, you have to completely reload the application to change the language
    • Only support translation in the template (by using HTML tag)
    • You need to build + deploy every time you make a change to the language, and you have to have a separate folder every time.
    • You can see the language in the URL.


    • It provides more powerful API support
    • It supports to JSON files by default to store the translation resources
    • It doesn’t provide good support for plural forms and date.
    • Ngx-translate will stop its releases when angular built-in modules catch up the ngx-translate features.
    • T he developer said that when Angular i18n catches up the library will be deprecated. Check article .
    • The simplest library to deal with multilingual.
    • Supports plural handling in different languages.

    • It compiles the translations during the compiling period, which doesn’t support the change of translation at any time.
    • Only supports AngularJS


    Ngx-translate provides the APIs which you can use to translate the resources in the code:



    By comparing of the 3 libraries we can see ngx-translate provides the best functionality now due to the API support, even though the built-in i18n module will catch up in a certain time, but we still recommend using ngx-translate for multilingual support in your Angular application.

  10. Do you detect service availability from the client?

    Some countries (especially the People's Republic of China) strictly control access to various international web services. You can use service detection to determine whether particular services are available and fall-back gracefully or use alternative providers.​

    As well as from inside China, another common place where access to third-party services may be blocked is from behind corporate firewalls.

    First, read this rule: Do you manage your 3rd party dependencies?. You should always start by carefully managing the number of 3rd party services and dependencies your application or website depends on.

    When you have identified an essential 3rd party service, you need to plan how to respond when that service is not available. There are 2 main options:

    Option 1: Fall-back gracefully

    The site will attempt to use this service and include its features, but if this is not available, the rest of the site will continue to operate normally.

    Option 2: Provide an alternative to the blocked service

    If, for example, your site displays videos, you can detect that YouTube is not available in China and embed YouKu videos instead. 

    Both these options require service detection to operate properly. Remember that attempting to connect to a blocked service from China could take a long time to timeout, potentially adding significant loading times to your site. 

    One possibility could be to use geolocation based on client IP to determine what services are available but this has a number of disadvantages.:

    • Geolocation based on IP is never perfect
    • You need to maintain lists of locations and what services are available there - which may be subject to change
    • This approach won't detect services that have been blocked by a company firewall.
    For these reasons, dynamic service detection is recommended in preference to solutions based on geo-location.

    SSW has created a simple Service Detection library for exactly this purpose called SSW Service Detector. This is open source and available from GitHub: SSW Service Detector.

    This Service Detector works by attempting to download the Favicon.ico file from the website for each service you want to use. These favicon files are small, so if a service is available, the file will download very quickly. If a service is blocked, the connection could take a long time to timeout on its own. In this situation, the service detector uses a 1.5-second timer to attempt the download and will cancel the request after this time so that these connection attempts fail quickly and don't block the entire page.

    Figure Bad Example: Attempted requests to Facebook, Google, and Youtube from China took a long time to timeout, adding significant delays to the rendering of this page
    Figure: Good Example - Only 4 errors on F12 in China. Using SSW.ServiceDetector, there were only short, canceled requests raised to blocked services. The site was then able to fall-back gracefully for some services and load YouKu for videos