j18n Tutorial

Build/Import

In order to integrate your j18n project with a SCC working copy, you import any existing resources and then build and download the output .jar

Build/Import List

Roles: Administrator, Developer
Plans: Paid
Navigation: Build/Import menu

Lists your previous builds (last 10) and imports.
Also, here you can schedule a new build. j18n only allows one scheduled/running build per project at a time.
The output of a build is a .jar file of standard java .properties files with appropriate path info. j18n will send an email to the user who scheduled the build/import when the job is finished.
Each build is listed with its status, type, when, and who scheduled the build.
Imports are similarly listed in the imports section. You can download the .jar that you uploaded and view a simple log file detailing what j18n processed. j18n only allows one scheduled/running import per project at a time.

- Schedule a Build

Choose the type of build (clean or incremental). The project's current build options are displayed (administrators only may click on the Build Options link to change build options)
Builds are done asynchronously (i.e. they are put on a queue). j18n sends an email to whomever scheduled the build when the build is complete.

- Clean Build

Simply builds your entire project taking into account a project's build options, path, resource inheritance, etc. The output .jar is suitable for directly adding to your project's classpath.

- Incremental Build

Builds only those resources that have changed since your last successful build; the algorithm is conservative—you can be certain that any resource that needs to be built will be; j18n will sometimes promote an incremental to a clean build (e.g. locale change, build options change, etc.)

Which type of build should you do?

Unfortunately, the best we can offer is, "It depends". What we can say is that incremental builds will generally be faster (and produce smaller .jars)
We do suggest however that you define a couple of simple tasks (Ant, Maven, your tool of choice), one that unzips the contents of the j18n build .jar into your SCC working copy, and another that then jars all of your java .properties files for deployment with your application (you probably already have done that). This enables you to use incremental builds and preview source (from IDE views) whenever you want.
For what it's worth, in developing j18n we tended to use incremental builds in combination with preview source, only doing a clean build when deploying to our production servers.

Import

Roles: Administrator
Plans: Paid
Navigation: Build List (button:import)

When you start working with a j18n project, one of the first things you will want to do is import any existing java .properties files. For the most part, if you have a working resources.jar, importing it will just work. But there are a few steps you need to take to ensure that nothing goes wrong.

First, setup your project. Specifically, correctly define your master and foreign locales; this is how j18n identifies a java .properties file as belonging to a specific locale and greps its base name:
menu.properties menu_fr.properties
If there is a foreign locale (fr) defined for the project, then and only then can j18n identify menu_fr.properties as being the french version of menu.
You must do this before scheduling an import.

Second, prepare your import file. This may require no work at all on your part, but there are a few restrictions.

Only .zip files may be imported (.jar files are essentially just .zip files)
Only proper java .properties files within the import .jar will be processed; i.e. any nested .jars, other files will be ignored.
The file size must be 4 megabytes (MB) or less (it is highly recommended that the java .properties files be compressed).

Always import all of your master resources first (of course including all of your resources master and foreign in the same .jar works). This is critical.
A few other notes: any comments in the java .properties files will be ignored and all content master or foreign will be ascribed to the scheduler of the import.
Imports are designed to be done once, at the start of your j18n project. There are no restrictions on the # of imports, but importing java .properties files that were built by j18n will typically not work, because there is no notion of resource inheritance in java .properties files.