NetBeans6.0L10NListHOWTO

HOWTO write l10n.list files for NetBeans 6.0

Contents


Introduction:

In this document you can read about new L10N kit process for NetBeans release 6.0. L10N kit process involves developers, translators and build engineers. Developers have to mark all localizable files, translators have to translate these files to other languages and build engineers have to build the multilanguage product. You'll learn about the new approach for marking localizable files for L10N kit content, and you will learn about the case when you may need to do some work and how the work would be different from previous NetBeans releases. Desired outcome of L10N kit process is that we are able translate all localizable files and build multilanguage. Developers have the responsibility to maintain pattern files, that are the foundation stone of the whole localization effort in NetBeans.

Changes

We have changed the L10N kit build process for NetBeans 6.0 to better match the needs of localization teams, while allowing Build Engineering for easy creation of L10N kits for various module configurations.

  • Before NB 6.0 we used to have one l10n.list file for whole CVS module.
  • Scope of the l10n.list file has changed:
  • from level of top CVS module to a level of NetBeans module project having project metadata under "${cvsmodule}/nbproject" subdirectory.
  • covers only files belonging directly to NetBeans module defined in "${cvsmodule}/nbproject"
  • Existence of the "${cvsmodule}/l10n.list}" file is not mandatory under following "OR" conditions
  • There is not a NetBeans module defined in "${cvsmodule}/nbproject"
  • There is a NetBeans module defined in "${cvsmodule}/nbproject" AND is correctly covered by global file
  • L10N kit creation process resurrected a feature for loading so called "global file". The global file contains patterns for the most usual/common cases what files should be put into L10N kit. You can find current version of this global file in nbbuild/l10n-global.list .
  • L10N kit build process has been modified to automatically load global file in case there's no local l10n.list file at NetBeans module level. This introduces major work offload from developers, because more than 85% of NetBeans modules are easily covered by patterns from this global list. However there are still about 10-15% of modules which need local override for various reasons.

What's the gain of this change?

  • Now we can have unlimited number of different L10N kits produced according to needs of localization teams
i.e. kits by clusters or groups of clusters
  • NetBeans module developer does not need to know into which kit(s) a module belongs, simply describes localizable files belonging to respective NetBeans module and that's it. Previous model where multiple developers had to edit one shared l10n.list file for whole CVS module has been changed is now granular per each NetBeans module.
  • Due to this granularity L10N kit content should have 100% match to product content. It's because one same list of NetBeans modules is used for product build and also for L10N kit build. This is supposed to help avoid unrelated modules getting into L10N kit and missing from product.

Vocabulary

CVS Module
top directory, first level directory under nb_all working directory
NetBeans module
a project, which can be opened as native project of NetBeans IDE, each such project has a nbproject subdirectory
L10N kit
a tarball containing all localizable resources for selected NetBeans modules
global list
one file describing the most usual L10N kit include&exclude patterns valid for majority of NetBeans modules
local override
l10n.list file put into root of a NetBeans module at the same level as nbproject directory

When to write local override?

Basic answer is whenever patterns in global list do not cover for localizable file(s) in your NetBeans module. You can try procedures mentioned in section How to build&check your module L10N kit of this document to get L10N kit for your NetBeans module(s) to see if it's your case. Only module owner knows what all resources should be sent for translation.

Known cases

  • You want to add a file, which is not covered by the global patterns
  • You need to execute some Ant target to generate localizable stuff
  • You want to include some files which are not under same root as your NetBeans module
  • NetBeans module has more source directories than just "src"
  • NetBeans module project lies in directory called 'javahelp' (i.e. core/javahelp)


Syntax of l10n.list file

Basic features

  • comments
Usual hash mark "#" used as very first non-whitespace character of a line
  • overriding behavior
if NetBeans module contains l10n.list file, then global file is implicitly ignored. However you can explicitly load it. See next point.
  • explicit read of global file
just write read global at very beginning of your l10n.list file and all patterns from global file would be applied in your module too, then you can add some more includes and excludes according to your needs
  • call of custom Ant target in your module's build.xml to generate localizable stuff
some modules do generate localizable stuff at buildtime, because the localizable stuff is not available in plain source base checkout. Just add antcall custom-target into your local l10n.list override and the L10N kit build will execute the 'custom-target' when it would be processing your module.
  • using JVM properties
reference them using Ant's style '${property.name}'. If you use multiple properties, please note that evaluation proceeds from left to right (check method resolveProperties() in L10nTask.java ).
  • referencing directory of current NetBeans module (self-reference)
current NetBeans module directory can be referred as '${l10n-module}'. It's always good to use this property instead of i.e. 'web/jspsyntax' string.
  • includes
implicitly any line not matching other syntax definitions in this list. If the line is "web/external/syntaxref20.zip", then it's include of this respective file.
  • excludes
a line starting with exclude string followed by path and filename specification. Use syntax of Ant's <fileset> excludes.
  • wild card masks
use regular Ant's wildcards, i.e. string "web/**/resources/**/*.gif" means all "*.gif" files anywhere under "web" directory and path must contain directory "resources" at any level under "web".
  • 'up-walking' relative paths
it's known bug that implicit include references like string '${l10n-module}/../external/syntaxref20.zip' do not work. In such a case use full path, which is 'web/external/syntaxref20.zip' in this particular case.Reason why it does not work is unknown at this moment.

l10n.list syntax examples

  • Comments in l10n.list
 # commented text
  • Call some custom target in your module
 antcall custom-target
  • Explicit request to load global file
 # load global file, if you want
 read global
  • Including additional files not covered by global file
 # implicit include path relative to top level (nb_all) directory
 web/external/syntaxref20.zip
  • Excluding some files
 # now let's define some excludes
 exclude web/jspsyntax/**/*.gif
  • JVM property reference
 # Now let's use some JVM properties
 ant/external/ant-docs-${ant.version}.zip
 exclude ${l10n-module}/src/**/Bundle-JSF.properties

Notes about these syntax constructs

Almost all syntax constructs can be used in both pattern files (global patterns file and l10n.list file). However there are some recommendations about proper usage of some constructs.

  • read global
It's recommended to not put "read global" line into global file as it would cause simple infinite loop (global file referring itself recursively w/o a way to exit).
  • antcall target
Calling custom targets may, but must not introduce a need to build part of the whole product first. This could be caused by possible use of build artifacts in your custom target, i.e. calling a class from a jarfile which is a result of build.
It's suggested to not put "antcall target" line(s) into global file as it could cause great difficulties when debugging L10N kit build output. However this functionality is not limited and should work (but it was not tested for use in global file).

How to build&check your module L10N kit

Build L10N kit for just one single NetBeans module

$ cd nb_all/nbbuild
$ ant -Dfixedmodules=web/jspsyntax -Dmodules= l10n-kit
$
use comma-separated list of paths relative to nb_all in case you want to build kit for more than one NetBeans module

Build L10N kit for known module configurations

$ cd nb_all/nbbuild
$ ant -Dmoduleconfig=visualweb l10n-kit
$
check nbbuild/build.properties file for known module configurations. Look for properties named config.modules.* resp. config.fixedmodules.*

Build L10N kit for your custom configuration

$ cd nb_all/nbbuild
$ echo 'config.fixedmodules.userconfig=${nb.cluster.ide}' >> build.properties
$ echo 'config.modules.userconfig=web/jspsyntax,web/css' >> build.properties
$ ant -Dmoduleconfig=userconfig l10n-kit
This example creates user-defined module configuration called userconfig. The configuration references the ide cluster via the ${nb.cluster.ide} property and adds two extra modules web/jspsyntax and web/css.
Please note that this procedure modifies version controlled file used for regular production. Before check-in please make sure the file has got only changes you wanted.

Notes

  • If you want to build L10N kit for more modules, set JVM properties fixedmodules and modules with comma-separated lists of your NetBeans modules
  • l10n-kit build is not yet ready for build by clusters, however you can either use moduleconfigs existing in nbbuild/build.properties file or you can define you custom configuration.

Checking content of L10N kit file

First some information about what is NetBeans L10N kit. It's a tarball, which contains other tarballs. One .tar file for each CVS module. Each 'inner' tarball contains files in structure relative to root of your working directory.

Usual structure may look like:

  • l10nkit.tar.gz
  • nb_all
  • core.tar
    • core
      • src
        • ...
          • Bundle.properties
      • core.l10n.list.all
  • openide.tar
    • openide
      • src
        • ...
          • Bundle.properties
      • openide.l10n.list.all

When you check your L10N kit, look into the ${cvsmodule}.l10n.list.all file first. It's simple text file containing filenames of all included files. Compare this list with what you think it should be in the kit. Please note that certain modules do generate localizable files. For example some modules under visualweb CVS module do generate Bundle-JSF.properties files, which should be included in L10N kit, but these files do not exist in CVS repository.

Suggestions && recommendations

Please do

  • if you externalize some non-localizable strings (i.e. bean's UID), put it into file called Bundle_noi18n.properties. The only exception is for "OpenIDE*" properties which must go into appropriate Bundle.properties file referred as "OpenIDE-Localizing-Bundle" in module jarfile's manifest.
This would help a lot to translators, because tool used for translation does show only the string for translation and completely ignores comments like "###### This section contains non-localizable strings ######".
  • In case you have to create local override, it's very likely you would profit from putting read global on very first line and then adding your exceptions (includes and/or excludes) specific to your module.

Please do not do

  • Do not add read global line into global file, unless you want test fan noise of your CPU
  • Do not use ${l10n-module} property reference together with up-walking relative paths (i.e. ${l10n-module}/../external/syntaxref20.zip), specify full path (relative to root of your workdir) instead (i.e. web/external/syntaxref20.zip)
  • Do not modify global file without cooperation with NetBeans Build Engineering and NetBeans localization team(s)
The target is to make patterns in this file describe all localizable files in 80% of NetBeans modules.
  • Do not anticipate Build Engineering writes {l10n.list</tt> file for you.
It's developer who must know what localizable resources are in the NetBeans module, thus developer must check accuracy of L10N kit and update l10n.list file whenever it's necessary. There's more than seven hundred (700) modules in NetBeans 6.0
Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo