internationalising a share customisation

#SummitNow

Internationalising a Share

CustomisationNovember 2013, Barcelona & Boston

David Webster / Alfresco Engineer

#SummitNow#SummitNow

Terminology:

Internationalisation or i18n

The engineering process to enable a piece

of software to be customised to a user’s

region.


Terminology:

Localisation or L10n

The process of taking internationalised

software and doing the customisation.


Terminology:

Locale

1. The user’s language and region

2. The identifier for the user’s language and

region, e.g. en_GB


Now in 11 Languages:

German: de

English (US): en

Spanish: es

French: fr

Italian: it

Japanese: ja

Dutch: nl

Russian: ru

Chinese (simplified): zh_CN

Norwegian: nb_no

Brazilian Portuguese: pt_BR


Internationalising Share


$ cat slingshot.properties


$ ls slingshot*.propertiesslingshot.properties

slingshot_de.properties

slingshot_es.properties

slingshot_fr.properties

slingshot_it.properties

slingshot_ja.properties

slingshot_nb_NO.properties

slingshot_nl.properties

slingshot_pt_BR.properties

slingshot_ru.properties

slingshot_zh_CN.properties


Using messages in your code


Else: Anywhere in JavaScript:

Alfresco.util.message(key, scope, var1…varN)


Setting messages in ftl

(Alfresco.component)

setMessages(${messages});


Setting messages in ftl

Alfresco.util.addMessages(${messages}, scope);


If: JavaScript extends

Alfresco.component.Base

this.msg(key, var1…varN)


If: AMD style widget in Share

4.2i18nRequirements: [{i18nFile: “./i18n/name.properties”}],

[…]this.message(key, var1…varN)


if AMD style widget:

• i18nRequirements: [{i18nFile: path}]

• this.messages(key, var1…varN)

else if Alfresco.component.Base

• .setMessages(${messages})

• this.msg(key, var1…varN)

else

• Alfresco.util.addMessages(${messages},

scope)

• Alfresco.util.message(key, scope, var1…varN)


In FreeMarker templates:

${msg(key, var1…varN)}


In JavaScript backed

webscripts:

msg.get(key, var1…varN)


File Encoding


Use ascii in *.properties files:

• 月 === \u6708

• ê === \u00ea

• ß === \u00df


Convert using native2ascii:

• native2ascii -encoding UTF8

file.utf8.properties file.acsii.properties

• native2ascii -reverse -encoding UTF8

file.ascii.properties file.utf8.properties


Best Practices


1. Don’t concatenate messages

BAD:

//search.results.start=There are

//search.results.end=search results

var msg = this.msg(“search.results.start”)

+ “ ” + results.length + “ ”

+ this.msg(“search.results.end”);


1. Don’t concatenate messages

Good:

//search.results =There are {0} search

results

var msg = this.msg(“search.results”,

results.length);


//search.results.none=There are no search

results

//search.results.singular=There is one search

result

//search.results.plural=There are {0} search

results

if (results) {

msg = this.msg(“search.results.” +

(results.length === 1) ? “singular” :

“plural”, results.length);

} else {

msg= this.msg(“search.results.none”);

}


1. Don’t concatenate messagesEN:

search.results.found=Showing {0} of {1} results for "{2}" within {3}…

DE:

search.results.found={0} von {1} Ergebnissen f\u00fcr ''{2}'' in {3}

werden angezeigt...

JA:

search.results.found={3}''{2}''\u3067\u898b\u3064\u304b\u3063\u305f

\u7d50\u679c\u306e{0} / {1}\u4ef6\u3092\u8868\u793a\u3059\u308b...

Or (UTF8)

search.results.found={3}''{2}''で見つかった結果の{0} / {1}件を表示する...


2. Separate Contexts


3. Be careful with single quotes• Double the apostrophe (’’) when you see bracket(s) ({})

in the same message.

• Do not double the apostrophe( ’) if there is no bracket

({}) in the same message.

• Do not double the apostrophe( ’) if you see an

apostrophe in the original English contents since it

should have been confirmed to be displayed properly.

http://blogs.sun.com/byuan/entry/best_practices_of_handling_apostrophes


4. Avoid localised commas## Dates

days.initial=S,M,T,W,T,F,S

days.short=Su,Mo,Tu,We,Th,Fr,Sa

days.medium=Sun,Mon,Tue,Wed,Thu,Fri,Sat

days.long=Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,

Saturday

months.short=Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec

months.long=January,February,March,April,May,June,July,August,

September,October,November,December


4. Avoid localised commas

• \u3001 === 、

• \u3001 !== ,


5. Use OOTB date formats


http://xkcd.com/1179/


6. Format dates client side


7. Allow for growth


8. No config in *.properties

10. Don’t forget number formats

9. Internationalise everything


Best practices:1. Don’t concatenate

2. Separate contexts

3. Be careful with

single quotes

4. Avoid localised

commas

5. Use OOTB date

formats

6. Format dates client

side

7. Allow for growth

8. No config in

*.properties

9. Internationalise

everything

10. Don’t forget number

formats


Localisation Community

http://crowdin.net/project/alfresco

http://addons.alfresco.com/


Questions?

• [email protected]

• @davidcognite

#SummitNow

internationalising a share customisation

Software