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)