Localizing a Plug-in Module

What can we do if want to localize a module:

• Prepare a module directly localized, i.e. contains the localizing bundles in module's jar or
• Prepare a module and its localizing update and distribute together via AutoUpdate or
• Prepare a localizing update for a already installed module (e.g. a module from NetBeans distribution) and distribute only this localization via AutoUpdate.

The first way is easy but not so handy, localization or branding should be separated out the functional code, should have own placement in files layout.

The other ways uses the AutoUpdate to provide module's localization. As said in Understanding AutoUpdate Descriptors each update can be a functional update (or a new module) or module's localization. The functional update are described by manifest element, the localizing updates are described by l10n element in AutoUpdate Descriptor.

l10n

The l10n is a sub-element of parent module element. The attributes of the module element must specify what module's it is localization, codenamebase attribute is acting as module identification.

That means if I have a (unlocalized) module org-myorg-module and have prepared module's localization org-myorg-module_cs then module attribute codenamebase is org.myorg.module and l10n element has the attributes langcode cs and module_spec_version 1.0.

<!ELEMENT l10n EMPTY>
<!ATTLIST l10n   langcode             CDATA #IMPLIED
                 brandingcode         CDATA #IMPLIED
                 module_spec_version  CDATA #IMPLIED
                 module_major_version CDATA #IMPLIED
                 OpenIDE-Module-Name  CDATA #IMPLIED
                 OpenIDE-Module-Long-Description CDATA #IMPLIED>

• langcode and brandingcode specify for what locale and branding are good for, e.g. langcode is cs for Czech localization
• module_spec_version and module_major_version specify for what version of module are targeted.
• OpenIDE-Module-Name - localized name of the module.
• OpenIDE-Module-Long-Description - localized description of the module. Both of them are shown in the Update Center Wizard.

How it works?

Each module contains some stuff as subject for localization or branding, this stuff must be separated out of sources and stored either in bundles or in gifs/pngs/etc. Thus localizing update contains only a jar with bundles and images and must contain a descriptor what module will be localized.

• jar file: jar file must have as same structure of folders as module what we want to localized, e.g. if the org-myorg-module looks like:

org --- myorg --- module --- Action.class
                         --- Bundle.properties
                         --- Icon.gif

then its localizing jar (for Czech locale cs) must have the structure

org --- myorg --- module --- Bundle_cs.properties
                         --- Icon_cs.gif

• descriptor: The localizing update descriptor specify in l10n element for what module and what version is the localization addressed.

Suppose we have a localizing update org-myorg-module_cs. What can to do with it:

• install it via AutoUpdate as single update of already installed org-myorg-module or
• install localization and module together.

AutoUpdate client checks the active locale and finds localizing update for all being selected modules, it means that if we have chosen org-myorg-module and cs locale active then the client will find across all enabled Update Centers Czech localization by module code-name and version. If found ant then select it too. In this example should found org-myorg-module_cs and select it.

Example module and its localization

Example module Hello (org-myorg-module code-name) adds to Help menu a dummy item Hello i.e. uses one label which can localized, see Module's NBM at org-myorg-module.nbm.

Update Descriptor of this functional module looks as:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module PUBLIC "-//NetBeans//DTD Autoupdate Module Info 2.3//EN" "http://www.netbeans.org/dtds/autoupdate-info-2_3.dtd">
<module codenamebase="org.myorg.module"
        homepage=""
        http://platform.netbeans.org/org-myorg-module.nbm"
        license="no-license.txt"
        downloadsize="0"
        needsrestart="false"
        moduleauthor=""
        releasedate="2006/02/16"
>
  <manifest OpenIDE-Module="org.myorg.module/1"
            OpenIDE-Module-Implementation-Version="060216"
            OpenIDE-Module-Long-Description="Real module Hello installs Hello menu item into Help menu."
            OpenIDE-Module-Module-Dependencies="org.openide.util &gt; 6.9.0.1"
            OpenIDE-Module-Name="module"
            OpenIDE-Module-Requires="org.openide.modules.ModuleFormat1"
            OpenIDE-Module-Specification-Version="1.0"
  />
  <license name="no-license.txt"><![CDATA[[NO LICENSE SPECIFIED]
]]></license>

</module>

Czech localization Ahoj (org-myorg-module_cs) see at org-myorg-module_cs.nbm.

It's localizing update descriptor looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module PUBLIC "-//NetBeans//DTD Autoupdate Module Info 2.3//EN" "http://www.netbeans.org/dtds/autoupdate-info-2_3.dtd">
<module codenamebase="org.myorg.module"
        distribution="http://platform.netbeans.org/articles/org-myorg-module_cs.nbm"
        license="no-license.txt"
        downloadsize="0"
        needsrestart="false">
  <l10n 
        langcode="cs"
        module_major_version="1"
        module_spec_version="1.0"
        OpenIDE-Module-Name="Ahoj"
        OpenIDE-Module-Long-Description="Czech localization of module Hello. Will localize name of Hello menu item in Help menu."
  />
  <license name="no-license.txt">
<![CDATA[[NO LICENSE SPECIFIED]
]]>
  </license>

</module>

Both sample modules are declared by Update Center at localization_example.xml.

If you do want to try out this example then just create new one Update Center. Open Options panel, switch into Advanced options, expand IDE Configuration | System | Autoupdate Types. In popup menu of Autoupdate Types invoke New, it creates new Update Center. Set http://platform.netbeans.org/articles/localization_example.xml into URL field. Then you can connect this Update Center in Update Center Wizard. Also you have to run the IDE with cs locale, i.e. start IDE with --locale cs option.

If you install only Hello module then new Hello menu item in Help menu. If you install also Ahoj localization then the Hello menu will easy change to Ahoj menu item. If you will start the IDE with an another locale then the original Hello menu item should be there.

Versioning