Introduction
When it comes to internationalising an angular web application, angular-translate [^] is the number one module to go to. With 49 releases since March 2013 and seven active authors (contributed 2000 lines of code and more), this module is evolving very fast with the angular framework.
Larger angular applications often create the necessity to load the translation tables at runtime. Instead of implementing translations for every language in source code and deploying all of them when a client connects, they must deploy only resources for the currently selected language.
In the module angular-translate, this can be accomplished with async loaders. The developer's documentation about asynchronous loading [^] is very detailed, especially on how to implement each loader. But as a reader, you have to dive deep into the implementation examples, to evaluate which loader fits best to your needs. This tip should give a short description of each loader, including an example HTTP request to load a new translation table, and defines a few recommendations, when to use them.
Internationalization (i18n) and Localization (l10n)
In the angular core documentation [^], internationalization and localization are abbreviated with i18n and l10n. For consistency, we will stick to these abbreviations in the tip.
Points of Interest
Following the current implementation [^], there are four types of loaders available to provide translation tables at runtime. Each of them has different characteristics, advantages and disadvantages.
Url Loader
The Url Loader has a very simple client implementation. For configuration, the loader takes a static URL as parameter, e.g. 'l10n/res.json'. When language resources are requested during runtime for 'en_US', the client sends the following HTTP request to the server:
GET /l10n/res.json?lang=en_US
Then it is up to the server, to resolve the request and return the correct language resources as JSON object.
When To Use It?
- When a thin, simple client implementation is needed.
- When you want to parse the query parameter
?lang= on the server and add some logic.
Package
Use package angular-translate-loader-url.
Static Files Loader
The Static Files Loader expects the language resources to be available on the server via direct HTTP requests. The Url of each language resource file must fit into a pattern [prefix][lang][postfix]. For prefix 'l10n/', lang 'en_US' and suffix '.json', this results in a server request like this one:
GET /l10n/en_US.json
The server once again must return a JSON object with the correct language resources.
When To Use It?
- When a thin, simple client implementation is needed.
- When the server stores each translation table in a separate JSON file ready to deploy.
Package
Use package angular-translate-loader-static-files.
Partial Loader
The Partial Loader extends the Static Files Loader to a [part] parameter. This parameter can be set manually, when certain parts of the application are loaded, e.g., a module or a controller. Additionally to the [lang] parameter, this value can be included in the request url. During configuration, the Partial Loader takes a url template. This template will be directly passed to the server, when the language is set or changed.
Example:
- template URL:
'l10n/{part}/{lang}.json' - part:
'main' - lang:
'en_US'
Get /l10n/main/en_US.json
Similar to the Static Files Loader, the server must keep the language resources in the correct pattern ready to deploy, when this URL is requested.
When To Use It?
- For modular applications, when only a part of the application is visited by the user.
- For large applications with language resources at enormous sizes.
Package
Use package angular-translate-loader-partial.
Custom Loader
Eventually, these loaders can't satisfy your requirements. Is there a possibility to get more control over the loading process in the angular client? Yes, there is the Custom Loader. For this loader, angular-translate injects the framework services $http and $q to directly implement the loading calls on. For further details on how to implement a Custom Loader, have a look at the corresponding section in the angular translate wiki page.
The http request depends on the custom implementation.
When To Use It?
- When full control over the loading process is needed
- When the costs of a custom loader implementation in the client are excelled by the benefits of the custom functionality
Using the Code
There are two example projects attached to this article. To test async resource loading, you have to host the examples in a HTTP server.
Host Example in a HTTP Server
If you are familiar with node, http-server [^] could be your tool of choice: Open a command line and browse to the folder containing the index.html file. Then type http-server to start the server. You can read the used ports in the command line output, it the server started up successfully. Any other server serving HTML files from disk will do it, too. It is helpful, if the server prints the received HTTP requests.
HTTP Requests
When you load the website in your browser, take a look at the HTTP requests the server received. After the initial HTTP GET, there should follow the loader-specific call mentioned above.
Summary
The four loaders provide a broad spectre of solutions. While Url Loader or Static Files Loader can be implemented fast and may be satisfying for the great majority of use cases, the other two allow highly specialized solutions. Partial Loader modularizes the language resources according to the application structure and Custom Loader provides a powerful lever to customize the translation resources' loading behavior at max.
References
History
- 9th February, 2016: Initial version
- 13th February, 2016: Example code added
