j18n Tutorial
Table of Contents
Introduction
Internationalizing and localizing software is not just a software engineer thing.
And it's not just a translator thing. Just about anyone can be involved in defining the content
of your software—product,QA, client services, management, engineers, translators.
It is a collaborative effort. Therefore, you need a simple tool that everyone can use
without impinging on engineering time and keeping your software artifacts isolated
And you need to be able to keep track and manage the localization, what's missing,
what's out-of-date, how much work is left. j18n is that tool.
Terminology
Resource— this is an overloaded term within j18n. For the most part
you can think of a resource ==> standard java .properties file; indeed, this
is the format that is output when doing a build.
But j18n breaks resources into two component parts:
One is structural: it consists of a name (and path), a set of keys (and associated
optional comment) and optionally a set of super-resources (those that it extends)
The important thing to note here is that there is no mention of a locale, i.e.
it is locale independent. Within j18n these are known as ResourceTemplates
The other component is about content; it contains the content for all of the keys that are
defined by its parent ResourceTemplate for a specific locale; internally we
term these ResourceInstances, in the sense that they are locale-specific instances
of ResourceTemplates.
So com.nomagicsoftware.j18n.resource.menu is a ResourceTemplate; while
com.nomagicsoftware.j18n.resource.menu_en
com.nomagicsoftware.j18n.resource.menu_de
are its ResourceInstances.
One result of this structure is that all ResourceInstances share the exact same
set of keys; within j18n it is forbidden for multiple ResourceInstances of the menu
ResourceTemplate to have different keys (or paths or super-resources)
Essentially what we have done is make explicit what has been heretofore
implicit; or, as one user put it, we just formalized what everyone has
always been doing
So how/where are keys defined?
One of the guiding principles in designing j18n is simplicity. Since software
engineers are used to working with java .properties files, j18n integrates the defining
of keys with the editing of content in a master resource (ResourceInstance);
so all keys are defined in the master IDE (along with their comments and content),
just as if you were editing a normal java .properties file. The point is that keys are only
defined once, in one place, the master resource (IDE). When editing foreign
resources (in the Foreign IDE), you do not need to re-specify keys (indeed, you can't)
Of course what this also implies is that you can edit (or delete) a key once,
and its effects are propagated through all of its sibling foreign resources (ResourceInstances).
It is this very explicit structure that enables j18n to provide many of its additional
features and power.
Master — within j18n and this document you will see mention of master
locale, master resources. Some might find it easier to substitute "default"
for master. The master locale is just the locale that the application is written in;
it must be defined (at minimum a language must be specified); now many shops
do not add the locale suffix to their master java .properties files (us included)—this is
simply a build option in j18n and is only relevant for builds.
Master resources (ResourceInstances) are just resources for the master locale
Incomplete — this is the key to the project
management facilities within j18n. j18n keeps track of the state of each message (key) in each
foreign resource, viz. whether it is up-to-date, out-of-date, missing, or intentionally
missing. All out-of-date and missing message are considered incomplete
and that status is reflected within j18n. In this way, you always know how much
localization work is left (at the project, locale, and resource levels).
Note: By definition, master locales and resources are never incomplete.
Sibling Resource — resources (ResourceInstances)
are siblings if they share the same parent ResourceTemplate, e.g.:
com.nomagicsoftware.j18n.resource.menu_en (the master)
com.nomagicsoftware.j18n.resource.menu_de (a foreign)
are sibling resources.
Quick Start
For those of you who never bother to read manuals . . .
- Setup Your Project (define master and foreign locales)
- Import Existing Resources
- Add Resources (ResourceTemplate)
- Enter Resource Content (in Master/Foreign/ToDo IDE)
- Build Your Project
- Add Users
There's also a quick IDE cheatsheet
You can be up and running in a few minutes (depending on the number/size of your imports)