Documentation

AJS.i18n

Summary

AUI includes a web resource transformer that will translate some javascript into the literal strings before being served.

Status

Examples

var label = AJS.I18n.getText("close.button");

will be translated by the transformer into:

var label = "Close";

Code

Using the transformer in your application

1. Add user locale to the caching url prefix

If your application serves javascript resources with a caching url prefix (typically done through the WebResourceManager if you use Atlassian Plugins), you'll need to update it to include the user locale so that the translated resources are invalidated when a user changes their configured language.

Prior to Atlassian plugins 2.8.0

For example, Confluence's caching url prefix is typically something like /s/BUILD_NUMBER/SYSTEM_COUNTER// and has been to be updated to /s/LANG/BUILD_NUMBER/SYSTEM_COUNTER// in Confluence's implementation of the WebResourceManager.

/**
     * Override to include user lanaguage in the prefix
     */
    @Override
    public String getStaticResourcePrefix(UrlMode urlMode)
    {
        // "{base url}/s/{lang}/{build num}/{system counter}/_"
        return webResourceIntegration.getBaseUrl(urlMode) + "/" + STATIC_RESOURCE_PREFIX + "/" + getLanguage() + "/" +
            webResourceIntegration.getSystemBuildNumber() + "/" + webResourceIntegration.getSystemCounter() + "/" + STATIC_RESOURCE_SUFFIX;
    }
 
    /**
     * Override to include user lanaguage in the prefix
     */
    @Override
    public String getStaticResourcePrefix(String resourceCounter, UrlMode urlMode)
    {
        // "{base url}/s/{lang}/{build num}/{system counter}/{resource counter}/_"
        return webResourceIntegration.getBaseUrl(urlMode) + "/" + STATIC_RESOURCE_PREFIX + "/" + getLanguage() + "/" +
            webResourceIntegration.getSystemBuildNumber() + "/" + webResourceIntegration.getSystemCounter() + "/" + resourceCounter + "/" + STATIC_RESOURCE_SUFFIX;
    }
 
    private String getLanguage()
    {
        Locale locale = localeManager.getLocale(AuthenticatedUserThreadLocal.getUser());
        return locale.getLanguage();
    }

In Atlassian plugins 2.8.0 or later

You need to implement getStaticResourceLocale() from WebResourceIntegration instead of overriding the two methods above.

2. Apply the transformer to your scripts

You need to mark which web resources you want the transformer to run on. You do this by adding some markup to your web resource definitions.

<web-resource key="labels-editor" name="Confluence Labels Editor" i18n-name-key="admin.web.resources.plugin.labels.editor.name">
        <!-- Applies the transformer to all js resources defined within this web resource -->
    <transformation extension="js">
            <transformer key="jsI18n"/>
        </transformation>
        
    <resource type="download" name="labels.js" location="/includes/js/labels.js">
            <param name="source" value="webContextStatic"/>
        </resource>
        <resource type="download" name="labels-editor.js" location="/includes/js/labels-editor.js">
            <param name="source" value="webContextStatic"/>
        </resource>
        <resource type="download" name="labels.css" location="/includes/css/labels.css">
            <param name="source" value="webContextStatic"/>
        </resource>
        <dependency>confluence.web.resources:ajs</dependency>
    </web-resource>

For the transformer to work, the syntax AJS.I18n.getText("key") must be used, where "key" must only contain letters, numbers, dots and hyphens.

Important Notes:

• it currently only supports double quotes around the key
• you cannot have the key be dynamically generated or have line breaks

The transformer is very simple (it does not parse javascript) and can only transform the static string in the above format.