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 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.

    There are two ways to determine service availability, these are:

    Option 1: Geolocation

    You can use geolocation based on client IP to determine what services are available but this has a number of disadvantages.:

    • Unpredictability Geolocation based on IP is never perfect
      Geo-location lookup services are not perfect. here's an example: if you use the guest internet in the Microsoft offices, the internet thinks you are outside Australia (Singapore).  
      This approach won't detect services that have been blocked by a company firewall.
    • Maintenance overhead You need to maintain lists of locations and what services are available there - which may be subject to change (however not very often)
      The list of services allowed/blocked by the "great firewall of china" is a moving target. things get blocked and unblocked all the time with little warning. we would have to keep coming back to the site to test. So there would be an overhead maintaining lists of countries and the services they allow.
    • Extra dependency - using IP address requires taking a dependency on an extra third-party service to perform the geo-location lookups. 

    For these reasons, dynamic service detection is recommended in preference to solutions based on geo-location.

    ​​Option 2: Check Connectivity  

    Universality - China is not the only place that blocks stuff. there are other countries to consider. Also many corporate firewalls block stuff. actively detecting access to a service from the client handles all these scenarios at runtime with no prior configuration.

    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


    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. 

    Solution 1: Remove the content

    [​TODO: JEAN - image of the youtube removed]

    Solution 2: Provide an alternative to the blocked service

    [TODO: JEAN - ​image of the youtube changed to yuku]

  10. Do you use CDN for JS files?

    ​​​In China, these changes are quite noticeable. The page load time can change from 8 seconds to 1 second.

    What is a CDN?
    CDN is short for the content delivery network. A content delivery network (CDN) is a system of distributed servers (network) that deliver pages and other Web content to a user, based on the geographic locations of the user, the origin of the webpage and the content delivery server.

    Why use a CDN in China?
    There are firewalls in China, which causes some external resources being blocked, and some JS packages having no servers in China, so they will load very slowly.​

    Which CDNs work well from China?

    Which ones do not work well from China?

    3. ​
    Figure: bad example: CloudFlare   MaxCDN
    F​igure: good example: CDNJS​

  11. Do you add multilingual support (Angular)?

    How to implement multilingual support in an Angular project?

    There are several ways of implementing multilingual support in an Angular project, the following libraries are popularly:
    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 can also be used in the code by APIs. 
    angular-gettext:  the simplest powerful 3rd party library providing 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 for 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 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 with the ngx-translate features.
    • The 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.

  12. Do you avoid reviewing performance without metrics?

    ​If a client says:

    "This application is too slow, I don't really want to put up with such poor performance. Please fix."

    We don't jump in and look at the code and clean it up and reply with something like:

    "I've looked at the code and cleaned it up - not sure if this is suitable - please tell me if you are OK with the performance now."

    A better way is:

    • Ask the client to tell us how slow it is (in seconds) and how fast they ideally would like it (in seconds)
    • Add some code to record the time the function takes to run
    • Reproduce the steps and record the time
    • Change the code
    • Reproduce the steps and record the time again
    • Reply to the customer:
      "It was 22 seconds, you asked for around 10 seconds. It is now 8 seconds."
     Figure: Good example – Add some code to check the timing, before fixing any performance issues (An example from SSW Code Auditor)

    Also, never forget to do incremental changes in your tests!
    For example, if you are trying to measure the optimal number of processors for a server, do not go from 1 processor to 4 processors at once:
    Figure: Bad Example - Going from 1 to 4 all at once gives you incomplete measurements and data

    Do it incrementally, adding 1 processor each time, measuring the results, and then adding more:
    Figure: Good Example - Going from 1 to 2, then measuring, then incrementally adding one more, measuring...
    This gives you the most complete set of data to work from.

    This is because performance is an emotional thing, sometimes it just *feels* slower. Without numbers, a person cannot really know for sure whether something has become quicker.


    For sample code on how to measure performance for windows application form, please refer to rule Do you have tests for Performance? on Rules To Better Unit Tests.

    Related Rule

  13. Do you use Gzip?

    Gzip is a file format and a software application used for file compression and decompression.
    Gzip can reduce file size and storage space, and reduce transmission time when transferring files over the network. It runs on both Linux and Windows.

    How to use PageSpeed to find which files on your site would benefit from being compressed with Gzip?

    what PageSpeed is?

    PageSpeed can analyze the performance of your webpages and get specific suggestions on how to optimize them.

    How to install PageSpeed?​

    Install PageSpeed from​
    select PageSpeed, choose the following extension, and install it:​2d.png

    Figure: Try to Install PageSpeed Insights.

    How to use PageSpeed?

    See in developer tool, you will have a new part named PageSpeed.

    Figure: Start your PageSpeed by clicking "ANALYZE".​

    See the refresh results from PageSpeed.

    1.pngFigure: Some files can be compressed more than 80%​

    Three ways to add Gzip compression to your site: ​

    Use one of the methods described below to add Gzip compression to your site ASP.Net/Angular website

    • Method 1: Turn on "Dynamic Content Compression" In IIS Server. 2.pngFigure: Choose the website which you want to use Gzip and click on Compression.​​​​3.pngFigure: Install "dynamic content compression" if you haven't installed it.​

    • ​​
      In Control Panel navigate to All Control Panel Items | Programs and Features , and click Turn Windows features on or off.
      Choose Internet Information Services | Web Management Tools | World Wide Web Services | Performance Features | Dynamic Content  ​Compression.4.pngFigure : Click "Ok" to install it.5.pngFigure: now enable dynamic content compression for your site.

      • ​​​Method 2:  Using “Gzipper” in your Angular website​
      • Follow .(but it still need IIS Server enable static content compression.)
        Using "npm i gzipper g" to install "gzipper" first. Add to scripts in your package.json​​​​

        6.pngFigure: "Finish configuration like that.

      • Method 3: ​​​​​​​​​​Using ASP.NET code in MVC​
      • Refer to . ​ To implement this in ASP.NET MVC, we can utilize ActionFilterAttribute and override either OnActionExecuting or OnResultExecuting method. The below code snippet is being used to check whether the current request browser can accept GZIP/DEFLATE encoding by looking at Accept-Encoding request header. If it finds GZIP encoding in this header, then we would set gzip in Content-encoding in response header and if it supports DEFLATE, then this code would set deflate in Content-encoding.
        using System;
        using System.Collections.Generic;
        using System.IO.Compression;
        using System.Linq;
        using System.Web;
        using System.Web.Mvc;
        namespace HTTPCompression.ActionFilters
            public class CompressAttribute : ActionFilterAttribute
                public override void OnResultExecuting(ResultExecutingContext filterContext)
                    HttpRequestBase request = filterContext.HttpContext.Request;
                    string acceptEncoding = request.Headers["Accept-Encoding"];
                    if (string.IsNullOrEmpty(acceptEncoding)) return;
                    acceptEncoding = acceptEncoding.ToUpperInvariant();
                    HttpResponseBase response = filterContext.HttpContext.Response;
                    if (acceptEncoding.Contains("GZIP"))
                        response.AppendHeader("Content-encoding", "gzip");
                        response.Filter = new GZipStream(response.Filter, CompressionMode.Compress);
                    else if (acceptEncoding.Contains("DEFLATE"))
                        response.AppendHeader("Content-encoding", "deflate");
                        response.Filter = new DeflateStream(response.Filter, CompressionMode.Compress);
        ​ [Compress] public ActionResult About() { ViewBag.Message = "Your application description page."; return View(); }

    Read more about Do you use Gzip?