- 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 language; to administer all supported languages.
- Located
org.argouml.i18n
- Layer
- Facade class
org.argouml.i18n.Translator
Public API
There is a facade class called org.argouml.i18n.Translator that is used for all accesses to the Internationalization.
How do I...?
...fix an incorrect or missing translation?
This is the responsibility of the language team.
If you are a member of the language team, commit the new translation.
If you are not, send your corrections to the correct team by mail or enter an issue in issuezilla. Each language team might want to handle this differently. Whatever way, it should is stated on the web site for that team. The language team members are the ones with the Developer role in the language project.
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 of the ArgoUML project.
For historic reasons there are currently (June 2005) teams without projects of their own. Projects will be created when something is to be done for these languages.
...verify that all translations are up to date?
There is a simple tool you can use that is developed in the argouml-gen project. Currently (June 2005) this tool is run regularly and a web page with the result published in the argouml-stats project.
...start a new Language Team?
Contact the project leader of the ArgoUML project to discuss this. He will create the project and make you the first member of the project once he is convinced that you have understood the responsibilities.
The projects are ArgoUML subprojects so they are listed at the bottom of the ArgoUML web page.
...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.
Make sure you are a Developer in the appropriate language project.
Look at the files in org/argouml/i18n, under argouml/src_new (in the argouml project).
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-language code/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
Join the dev mailing list in the correct project and apply for an Observer role in the project.
Discuss with the Language Team in question by mailing on the dev list. 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 or some argouml module.
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 file 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:
import org.argouml.i18n.Translator;
...
String localized = Translator.localize(key);
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.
Contact all language-teams so that they can update their files?
Currently (November 2003) there is 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.
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 string 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 these kinds 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, ... Also a user, changing the language, should not have his files or configuration corrupted by this change.
Design of the subsystem
When ArgoUML starts it starts with the language given by the first decisive language information of
- Command line argument
- The prepared Java Web Start alternatives also use this to override everything else.
- The users' saved configuration
- The default locale for the users' computer
- ArgoUML default language (English U.S.)
This is done independently of if ArgoUML has that language prepared or not.
Example 5.1. Starting with nonexisting language.
If ArgoUML is started with Swahili on the command line (that doesn't exist), while the user has French (that does exist) configured, ArgoUML will work in Swahili and all languages will show up in English U.S. i.e. the default language because Swahili doesn't exist.
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/argouml-app/src/org/argouml/i18n - functionality, and non-localized default language (US English), and partly in argouml-language/src/org/argouml/i18n - all files for a specific language (one new tigris project for each language).
In ArgoUML internationalization (sometimes called i18n) is done using the property files that are loaded into PropertyResourceBundles.
See also: Organizing translators and Ambitions for localization