ColdBox Developer Week 2014 Presentation http://www.coldbox.org/cbdw

2. About Me
 Working & living in İstanbul
 Coding since ‘85, CGI Programming since ’94 (Perl, C/C++)
 ColdFusion Developer since ’97
 Interested in ColdFusion, Flex, AIR, Ruby, Ajax,
Frameworks, i18N, L10N, G11N, Geolocation
 Created projects in more than 20 languages! 
 Have big interest in Epistemology
 Personal blog: http://blog.demirkapi.net

3. Getting basics on i18N
Theory

4. Do we need multilingualism?
 Yes!

5. Why i18N (Internationalization)?
 English is just another language.
 The World Wide Web should be truly world-wide!
 Internationalization is important to ensure that users worldwide can
equally benefit from Web technology.
 Wide diversity world-wide:
 Scripts (Latin, Cyrillic, Hebrew, Tamil, Katakana,...)
 Languages (English, German, Turkish, Korean, Japanese,...)
 Typographic conventions
 Cultural conventions
 Political circumstances
 Avoid fragmentation of specifications due to localization.
 Make sure internationalization is done at the right place.

6.  What is i18N (Internationalization)?
 Application functions in at least two locales
 What is L10N (Localization)?
 Process of applying a locale or language "skin" to an
I18N application
 What is G11N (Globalization)?
 i18N & L10N
What is …?

7. Internationalization & Localization
Globalization
 Single character set
 Single executable
 Single install
 Single server serves all clients
in all languages
Localization
 Based on globalized software
 Adds specific translations and
adaptations for particular
languages and markets
Globalized software can be localized without any code changes

8. Character encoding
Character encoding specifies mappings from a character
set to the integer numbers that represent the characters
on a computer.
 EUC-JP (Japanese)
 EUC-KR (Korean)
 ISO-8859-1 (Western European and English)
 SHIFT_JIS (Japanese)
 UTF-8 (All Languages)

9. What is Locale?
The combination of a language and a country code
 en_US: US English (color, $)
 en_GB: British English (colour, £)
 de_CH: German in Switzerland
 tr_TR: Turkish in Turkey

10. Selecting/Detecting Locale
 Manual
 Default locale can be loaded and other options would be
available by selection via buttons/selects etc.
 Locale Detection
 Parsing ‘Accept-Language’ header on HTTP request
 Not usable with URLLoader
 Capabilities.language property in Flash Player and AIR
 Parsing browser and OS language settings via JavaScript
 Location detection depending on IP

11. What is Unicode?
 Unicode (unicode.org) is an character set for all the
characters and symbols of the world.
 Unicode provides a unique number for every character.
 Except Klingon! 
؟ "يونِكود"ما هيالشفرة الموحدة
Unicode nedir?
Τι είναι το Unicode
Cos'è Unicode?
유니코드에 대해?
Что такое Unicode?

12. Unicode (cont.)
 Why do we need to use Unicode?
 Avoids data corruption
 Single encoding for text in all languages
 Makes software globalization possible
 Vastly reduces development cost
 Vastly reduces maintenance, update and support cost
 Switching to Unicode has no disadvantages for single language
users, to the contrary it usually offers advantages even for single
language users. And it offers great advantages for multilingual
users.
 Encoding: Use Unicode wherever possible for content,
databases, etc. Always declare the encoding of content.

13. i18N & web technologies
i18N & Web

14. Unicode & Files
 UTF-8 is the recommended encoding for files.
 Use a Unicode capable editor (IDE)
 ColdFusion/Flash Builder
 Default encoding is UTF-8
 Eclipse
 Default encoding is Cp1252
 Change it into UTF-8
 Window-> Preferences -> General -> Workspace
 Text file encoding
 No BOM creation
 OK for current files with BOM

15. Unicode & Files (cont.)
 Dreamweaver
 Supports full Unicode when selected
 Support BOM (Byte Order Mark)
 Homesite/CFStudio Never!
http://www.adobe.com/go/tn_19059
 Notepad
 The best tool! 

16. Unicode & Database
 Use a robust database with right settings
 MS SQL Server
 MySQL Server
 PostgreSQL Server
 Oracle
 Beware of Unicode Support
 MySQL 4.1 and up
default-character-set=utf8
character-set-server = utf8
collation-server = utf8_general_ci
 MS SQL Server
 SQL Server nvarchar, ntext etc.

17. i18N & CFML Platform
i18N & CFML

18. ColdFusion History
 Supports Unicode starting from ColdFusion MX
 Use ColdFusion MX
 If possible ColdFusion MX 7.x and up
 Use Updated JVM
 Set Required Locale

19. ColdFusion & Databases
 Use DSN Settings
 MS SQL Server
 String Format
 Enable High ASCII characters and Unicode for data sources
configured for non-Latin characters
 MySQL
 Select MySQL 4/5 driver

20. ColdFusion & Files
 Use Unicode
 If possible with BOM support
 ColdFusion MX Detects BOM
 If you have BOM support on your file ColdFusion
understand your locale and there is no need to use extra
tags such as cfprocessingdirective

21. ColdFusion & Files
 ColdFusion MX Templates
 If there is no BOM
<cfprocessingdirective pageencoding="utf-8">
must be included in every CFM template.
 Using in Application.cfm or cfc etc. does not help

22. ColdFusion & Tags & Functions
 Beware of ColdFusion Functions & Tags
 CFPROCESSINGDIRECTIVE, CFCONTENT, CFFILE, CFHEADER, CFHTTP,
CFHTTPPARAM, CFMAIL, CFMAILPART tags and the SETENCODING,
GETENCODING, TOBASE64, TOSTRING, URLDECODE, and URLENCODEDFORMAT
functions etc.
 Use encoding in Tags
<cfmail to="#user#" from="#me#" subject="Unicode Test" charset="utf-8">
<cfmailpart charset="utf-8" type="plain“>#mymailasplaintext#
</cfmailpart>
<cfmailpart charset="utf-8" type="html“>#mymailashtml#
</cfmailpart>
</cfmail>

23. HTML & i18N
 Multipart POST
<form action="#FOO#“ method="post"
enctype="multipart/form-data: charset=utf-8“>
 HTML/XHTML
<meta http-equiv="Content-Type" content="text/html;
charset=utf-8" />
 Detect Locale
 cgi.HTTP_ACCEPT_LANGUAGE
 IP & GeoLocator

24. Code & Language Isolation
 MVC Benefits
 Java Resource Bundles
 JRB General usage with CFCs
 IBM ICU4J Library
 GNU GetText ()
 Database
 XML

25. Java Resource Bundles
 Resource Bundle Tools
 RM Manager (http://www.icu-project.
org/repos/icu/tools/trunk/unicodetools/com/ibm/
rbm/docs/index.html)
 Attesoro (attesoro.org)
 Eclipse Plugin (sourceforge.net/projects/eclipse-rbe/)
 Web based (www.jmpj.net/rbMan/)

26. i18N in ColdBox
 ColdBox has an i18N plugin
based on Java Resource Bundles
http://wiki.coldbox.org/wiki/I18n.cfm

27. ColdBox config changes:
//i18n & Localization
i18n = {
defaultResourceBundle = "includes/i18N/main",
defaultLocale = "en_US",
localeStorage = "session", // default session, cookie, client, session, request
unknownTranslation = "**NOT FOUND**"
};
Activating i18N Support

28. Loading Plugins
 Base i18N Plugin
getPlugin("i18n")
 Resource Bundle Plugin
getPlugin("resourceBundle")

29. Base i18N Methods
 Get user’s current locale
getfwLocale()
Get the current user's locale from the locale storage
 Set a specific locale
setFWLocale( valid_locale )
Set the current user's locale, internally it uses the locale storage
assigned
 getResource(resource, [default], [locale], [values])
Get a language resource from the default user's locale or a
specific locale and even do array/struct/string replacements via
positional or named {} patterns: {1}, {2}, {username}, {lastName}

30. Prc Scope Usage
 Prc scope usage
function onRequestStart(event,rc,prc) {
prc.i18n = getPlugin("i18n");
}
A common practice for localized applications is to store a
reference to the i18n plugin object in the prc scope for easy
access throughout your application so you are not constantly
calling getPlugin("i18n") all over the place if you need to rely
heavily on i18n methods.
This is a performance optimization best practice.

31. // function change a user's locale
function changeLocale(event,rc,prc) {
setFwlocale(rc.locale);
setNextEvent('home‘);
}
<cffunction name="doChangeLocale" access="public" returntype="void"
output="false">
<cfargument name="event" type="any">
<--- Change Locale --->
<cfset getPlugin("i18n").setfwLocale(event.getValue("locale"))>
<cfset event.setNextEvent('main.home')>
</cffunction>
Changing Locale

32. i18N Methods
 getLocales(), isValidLocale()
 getISOlanguages(), showLanguage()
 getISOcountries(), showCountry(), showISOCounty()
 getAvailableTZ(), getServerTZ(), i18nDateTimeFormat(), i18nDateFormat(),
i18nTimeFormat(), getLocaleQuery(), getTZQuery(), getTZDisplayName() ,
usesDST(), getDST(), inDST()
 i18nDateAdd(), i18nDateDiff()
 isBidi()
 getCurrencySymbol(), getDecimalSymbols()

33. Sample Method Usage
rc.now = getPlugin("i18n").toEpoch(now());
rc.locales = getPlugin("i18n").getLocales();
rc.lang = getPlugin("i18n").showLanguage();
rc.country = getPlugin("i18n").showCountry();
rc.timeZones = getPlugin("i18n").getAvailableTZ();
rc.serverTZ = getPlugin("i18n").getServerTZ();
rc.laterOn = getPlugin("i18n").i18nDateAdd(rc.now,"hour",hours,rc.thisTZ);
rc.usesDST = getPlugin("i18n").usesDST(rc.thisTZ);
if (rc.usesDST) rc.inDST=getPlugin("i18n").inDST(rc.now,rc.thisTZ);
rc.tDate=getPlugin("i18n").i18nDateFormat(rc.now,rc.dateF,rc.thisTZ);
rc.tDateTime=getPlugin("i18n").i18nDateTimeFormat(rc.now,rc.dateF,rc.timeF,rc.thisTZ);
rc.tzOffset=getPlugin("i18n").getTZOffset(rc.now,rc.thisTZ);

34. Using Resource Bundle
 Get basic resource based on default or a specific locale
getResource(resource,[default],[locale])
#getresource("login")# // gets the login content for active locale
 Get complex resource
<cfscript>
oRB = getPlugin("resourceBundle");
footerParams = ["Oğuz Demirkapı", "http://blog.demirkapi.net"];
</cfscript>
#oRB.formatRBString(getResource('footerNote'),footerParams)#

35. Parameters in Resource
 <cfset oRB = getPlugin("resourceBundle")>
 <cfset orderDetails = ArrayNew(1)>
 <cfset orderDetails[1] = "Luis Majano">
 <cfset orderDetails[2] = "1-800-CallOrtus">
 <cfoutput>#oRB.formatRBString(getResource('confir
mMessage'),orderDetails)#</cfoutput>

36. DEMO

37. Designing i18N Application
i18N Application Design

38. Content Structure
 Same content in every locale
 Mirroring sites
 Isolated templates and contents
 Different content tree in different locales
 Roots for trees
 Complex tree referencing

39. Database Modeling
 Designing Database
 Locale definitions
 Content related pages have a flag field as locale.
 Lookup tables have i18N key in table and gets the content from RB
tools
 Tables vs. Fields
 Creating flags for any locale based content would be best practice
instead of creating different tables.
 Content Types
 Isolating localized content
 All content should be isolated in specific locales
 Saving localized content
 A localization manager would be a proper tool

40. Sample i18N Applications
 ContentBox (http://gocontentbox.org)
 MuraCMS (http://getmura.com)
 FarCry Core (http://farcrycore.org)
 ColdBox (http://coldbox.org)
 CFWheels (http://cfwheels.org)

41.  Unicode
Resources
 http://unicode.org
 Adobe Developer Center
 http://www.adobe.com/devnet/coldfusion/localization_globalizatio
n.html
 Globalizing ColdFusionMX (Paul Hastings)
 http://www.sustainablegis.com/blog/cfg11n/
 RBMan
 http://rbman.riaforge.org
 ColdBox Wiki
 http://wiki.coldbox.org/wiki/I18n.cfm
 My blog
 http://blog.demirkapi.net

42. Questions & Answers
?
Oğuz Demirkapı
http://blog.demirkapi.net
demirkapi+ColdBox@gmail.com