5.13. Internationalization

Purpose - to provide the infrastructure that the other subsystems can use to translate strings; to provide the infrastructure that makes it possible to plug in new languages; to administer the default (English U.S.) language; to administer all supported languages.

The Internationalization is located in org.argouml.i18n in the class path. In the checked out copy of ArgoUML it is located partly in argouml/src_new/org/argouml/i18n - functionality, and non-localized default language (US English), and partly in argouml/src/i18n/language/src/org/argouml - all files for a specific language.

The Internationalization is an Infrastructure subsystem. See Section 4.3, “Low-level subsystems”.

In ArgoUML internationalization (sometimes called i18n) is done using the property files i.e. PropertyResourceBundles. We used to have ListResourceBundle classes instead but they are all gone by 0.15.3.

5.13.1. Organizing translators

The problems with internationalization are not so much the technical problems as to how it works but more so the problems are with getting, keeping and coordinating the correct competences to do the job. This comes from the fact that by necessity the different persons working with internationalization have different native languages and that complicates the communications.

To handle this problem for GNU applications there is a community set up around “gettext” with one language team per language working with all “gettext” applications. There are also tools to help the translator do his job delivered with “gettext” that are the same for all the applications. In each of these language teams discussions are held that ensure a consistent use of words over all these applications.

It is for me (Linus Tolke, May 2002) unclear if and how such a community exists for Open Source Java tools and ArgoUML cannot simply benefit from the “gettext” communities since we don't use “gettext” and cannot use the same tools.

To get things done, we organize our own Language Teams with ArgoUML. Each language team is actually just one or several persons that know that language and are eager to work with translating ArgoUML.

The language team has the following responsibilities:

  1. All localized strings and resources shall be translated into the language.

    This is a constant work with keeping up with the changes that will be made to the ArgoUML code since ArgoUML is under fast development.

  2. The terminology used shall be correct.

    This requires work in keeping up with the current literature in the domain of ArgoUML.

  3. Help with the improvements on ArgoUML by pin-pointing where ArgoUML needs to be modified to allow for localization.

    As ArgoUML is originally built without localization we still have places in the GUI that is not localizable just by modifying the resource bundles. Each such place is a Defect and shall be corrected.

  4. See that the used libraries also provide their part in that language.

    This is mostly GEF since GEF is central both when it comes to the fact that it has localized strings of its own but also because it handles parts of the localization.

    This means discussing with the teams developing the underlying package as to how best to provide the localization for those parts. Either by providing localization for that team to include in the package or by having ArgoUML overriding that package in that respect.

5.13.2. Ambitions for localization

Let me (Linus Tolke, May 2002) try to define the levels of ambition for us to try to make it possible to discuss where we are going.

  1. No translation

    This is the lowest level of ambition that is a "do nothing"-level. This goes for all languages where we have not done anything like Swahili, Polish, South African English, ...

  2. Tool translation

    This is the basic level of ambition that each Language Team should aim for. It means that within ArgoUML all strings are localized so that ArgoUML is giving a complete appearance of being a tool for that language.

    Setting this level of ambition for a language (or creating a team for the language) is pointless if there is no window system available for the language in questions. I mean, if neither the people working with Windows, Linux (KDE or Gnome) or java has collected enough interest to do a translation of the basic infrastructure there is no point in doing so for ArgoUML. (My Windows 2k has 80 supported languages so I would think that this is a no-issue.)

  3. User environment translation

    This is the next level of ambition that can be set out by a Language Team that works really well and has plenty of translation resources left.

    It means that not only the ArgoUML tool should be translated but also everything around it that the user sees i.e. the User Manual, the Quick Guide, the FAQ, the Users' part of the ArgoUML Web site.

    Setting this level of ambition for a language is pointless if the problem domain does not exist in that language. I mean, if the professionals that use UML or other Software Engineering tools, in their every day work don't use their native language to discuss UML concepts, then there is no use in translating these concepts to their language, they will not use the translation because they are more comfortable with the English concepts. Note that the UML Specification does only exist in English and a natural part of this level of ambition would probably be to translate that.

  4. Development environment translation

    Here I mean that everything that the developer of ArgoUML sees is translated.

    We don't do this in the ArgoUML project.

    This begins with this Cookbook, then the Developers' part of the ArgoUML web site and also includes the javadoc comments in the code of ArgoUML and design documentation of included packages such as GEF, NSUML...

5.13.3. How do I ...?

  • ...fix an incorrect or missing translation?

    This is the responsibility of the language team. Send your corrections to the correct team by mail or enter an issue in issuezilla. The language team members are listed in the Developer Zone.

    If the language team does not do its work quickly enough (or well enough in your opinion), please volunteer to help them out by joining the team.

    If the language team does not respond, contact the project leader.

  • ...verify that all translations are up to date?

    Run checkstyle on the i18n parts. This is done from argouml/src_new with the checkstyle-i18n target.

    Search for comments on keys.

    Observe that the reported filenames are in the argouml/build directory even if the changes are supposed to be made in argouml/src/i18n/language/src/org/argouml/i18n!

  • ...start a new Language Team?

    Contact the project leader to discuss this. He will create the team once he is convinced that you have understood the responsibilities.

    The Language Teams are listed on the web page of language teams on the Tigris site. As soon as the language code and names (at least one) are in place the team is created.

    From that point it is the Language Team's responsibility to do a good job.

  • ...find the languages internationalization code for the language your instance of ArgoUML is attempting to run with: en, es, en_GB,...

    The one you are currently using is shown in the Versions information in the about box. Help Menu => About ArgoUML Menuitem => Version tab just after the Operating System information. Search for the text looking like this:

    Language: sh
    Country: KR
    

    This example means that you have your computer set to Swahili as spoken in Korea (I think). Notice that the Language: and Country: are localized and could appear in your language.

  • ...start the translation work?

    This is only applicable for members of the language team.

    Look at the files in org/argouml/i18n, under argouml/src_new.

    Translate all the values in each of these files.

    This is a lot of extremely qualified work including searching well-known literature on UML and Software Engineering in order to get the correct terms for the domain. Discuss with other UML and Software Engineering professionals with the same native language to get it right.

    Create the files with the translations and store them in argouml/src/i18n/language/src/org/argouml/i18n. They will have names like: action_language code.properties, button_language code.properties, checkbox_language code.properties, combobox_language code.properties, ...

    When this is done the first iteration of the Tool translation is completed. The work will probably be more maintenance-like from here on.

  • ...join an existing Language Team

    Discuss with the Language Team in question by mailing the members. They will hopefully have work prepared for you and greet you with open arms.

  • ...add or modify code with localized things?

    This is only applicable for developers working with the ArgoUML Java source.

    1. Everywhere the user would see a string in the GUI you should localize a key.

      This means that instead of writing a string you write a call to a localizer method with a "key" ("label" or "tag") as argument and the localizer method finds the resolution of the "key" is in one of the property files. You select one of the files for you key and name the key accordingly.

      The key is a string. The key has a special syntax like this:

          word1.word2.word3
      

      where word1 is the same as the first part of the filename that the key resides in. Example: The key "action.about-argouml" resides in the files action.properties and action_language code.properties.

      You will have to call the class org.argouml.i18n.Translator to convert them to wherever they are used.

      This is how a real example would look like:

      import org.argouml.i18n.Translator;
      ...
          String localized = Translator.localize(key);
      

    2. Add your "key" and resolution in English (U.S.) in the non-localized properties file in argouml/src_new/org/argouml/i18n and test that the GUI looks good for the default language.

      Which property file ArgoUML will eventually use depends on the localization settings of the running ArgoUML instance. While developing you should use en_US or some language that does not have a translation so that you can work with the default language.

    3. Contact all language-teams so that they can update their files.

      Currently (November 2003) there is a great confusion as to where we stand on the different translations. For this reason we can't say if any language team is up to date with the changes and served by such a contact.

    4. If you have strings that are sentences where you have dynamic values like a file name, a class name, or some property to enter at a certain place, remember that all languages would not write it exactly like that. Use MessageFormat to build every such sentence! There is a convenience function for this in Translator called messageFormat.

    Notice that if you somewhere change the meaning of a specific localized thing it would be a good idea to use a new "key" for the new meaning. This will make it easier for the translation team to spot the modification.

    There allegedly are tools in the java world to spot this kind of changes. Until we have the tools and processes in place to handle them it is better to rely on this simpler mechanism to guarantee correctness.

    Notice also that you shouldn't localize log entries, comments, exception names, names of environment variables, and tags and tokens used in save files. This is because the development project of ArgoUML is a one-language community (en_US) and the users of ArgoUML would want to be able to run an ArgoUML localized differently with otherwise the exact same settings, loading and saving the same files, ...