Localized XML Elements

From Apache OpenOffice Wiki
< Documentation‎ | DevGuide
Revision as of 09:56, 13 May 2009 by OOoWikiBot (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search




Some information contained in the description.xml are localized. When the Extension Manager uses them then it picks out the part which matches best the locale of OpenOffice.org. Localized data is used for

  • License files (simple license, since OOo 2.0.4)
  • Publisher name and URL for publisher homepage (since OOo 2.4)
  • URL for release notes (since OOo 2.4)

Localized data is typically expressend in this format:

<parent>
  <child lang="en-US" />
  <child lang="en-GB" />
</parent>

The children of <parent> have all a lang attribute, which have a language string according to RFC 3066. The following restrictions currently apply:

  • OOo uses only lang-country
  • the language string can only have one variant, for example de-DE-mitte
  • OOo uses uppercase letters for the country. The language strings must also use uppercasse letters for the country. That is, the comparison between the OOo's locale and the locale strings of the elements is case sensitive.


Let's assume that OOo uses British English (en-GB) end the extension has two license text files, one in German (de) and the other in English from New Zealand (en-NZ). Obviously there is no perfect match, since en-GB is not en-NZ. We would then probable prefer en-NZ over de. The algorithm tries to find a locale witch is closest to the office's locale. Here is the algorithm:


Input to the algorithm:

  • The <parent> element
  • The locale of the office

Requirements:

  • The <parent> element has at least on child
  • All children have the same element name and namespace
  • All children have a lang attribute

Output of the algoritm:

  • A child element (immediate child) of parent.

Algorithm:

  1. The language, country and variant part of the office's locale are used to find a matching child element. If there is an exact match then the respective child element is selected as output and we are done. Only the first match is used.
  2. The language and country part of the office's locale are used to find a matching license-text. If there is an exact match then the respective child element is selected as output and we are done.
  3. The language and country part of the office's locale are used to find a matching child element. This time, we try to match only the language and country parts. For example, the office locale strings “en-US”, “en-US-east” match the lang attribute with the values “en-US-north”, “en-US-south”,etc. The first child element with a matching lang attribute is selected as output. If there is a match then we are done.
  4. Only the language part of the office's locale is used to find a matching child element. If there is an exact match then the respective child element is selected as output and we are done. Only the first match is used.
  5. Only the language part of the office's locale is used to find a matching child element. This time, we try to match only the language part. For example, the office locale strings “en”, “en-US”, “en-US-east” match the lang attribute with the values “en-GB”,“en-GB-north”, etc. The first child element with a matching lang attributed is selected as output. If there is a match then we are done.
  6. The first child element will be selected as output.

Please note that before OOo 2.4 the algorithm for determining the default child element for the <simple-license> element was different. Then the parent element, which was <simple-license> had the attribute default-license-id (type IDREF)and one child, that is a <license-text> element, must have had a license-id (type ID) attribute. Both attributes needed to have the same value. While this was easy to be verified with a schema it was quite cumbersome to write. With OOo 2.4 the first child element is the default in case there was no other child with a matching locale. The old "style" will still be supported but it should not be used anymore for new extensions. It is also recommended to use the new "style" when providing a new version of an extensions, where the previous version used the old "style".


The following examples show what values would match with a piece of a description.xml. The locale of OOo is assumed to be en-US.

Example 1:

<simple-license accept-by="user" >
  <license-text xlink:href="lic_en" lang="en" />
  <license-text xlink:href="lic_en-GB" lang="en-GB" />
  <license-text xlink:href="lic_en-US" lang="en-US" />
  <license-text xlink:href="lic_en-US-region1" lang="en-US-region1" />
</simple-license>

The <license-text> with lang=”en-US” will be selected. This is a perfect match.


Example 2:

<simple-license accept-by="user" >
  <license-text xlink:href="lic_en" lang="en" />
  <license-text xlink:href="lic_en-GB" lang="en-GB" />
  <license-text xlink:href="lic_en-NZ" lang="en-NZ" />
  <license-text xlink:href="lic_en-US-region1" lang="en-US-region1" />
  <license-text xlink:href="lic_en-US-region2" lang="en-US-region2" />
</simple-license>

The <license-text> with lang="en-US-region1" will be selected. There is no "en-US" and the algorithm looks for any variant of "en-US" and takes the first one it finds.


Example 3:

<simple-license accept-by="user" >
  <license-text xlink:href="lic_en" lang="en" />
  <license-text xlink:href="lic_en-GB" lang="en-GB" />
  <license-text xlink:href="lic_en-NZ" lang="en-NZ" />
  <license-text xlink:href="lic_en-region2" lang="en-region2" />
</simple-license>

The <license-text> with lang="en" will be selected. There is no "en-US" nor the same locale with a variant, for example "en-US-region1". The next step is to compare only the language part. Then there is a match with lang="en".


Example 4:

<simple-license accept-by="user">
  <license-text xlink:href="lic_de" lang="de" />
  <license-text xlink:href="lic_en-GB" lang="en-GB" />
  <license-text xlink:href="lic_en-NZ" lang="en-NZ" />
  <license-text xlink:href="lic_en-region2" lang="en-region2" />
</simple-license>

The <license-text> with lang="en-GB" will be selected. There is no "en-US" nor the same locale with a variant, for example "en-US-region1". There is also no match when using only the language part. Then we look for a value that matches at least the language no matter what country or variant is used. The first locale that matches is "en-GB".


Example 5:

<simple-license accept-by="user" >
  <license-text xlink:href="lic_de" lang="de" />
  <license-text xlink:href="lic_de-DE" lang="de-DE" />
  <license-text xlink:href="lic_fr" lang="fr" />
</simple-license>

The <license-text> with lang="de" will be selected. There is no locale which even has "en" as language, so we just use the first entry as a default.

Example 6:

<simple-license accept-by="user" default-license-id="de" >
 <license-text xlink:href="lic_es" lang="es" />
 <license-text xlink:href="lic_fr" lang="fr" />
 <license-text xlink:href="lic_de" lang="de" license-id="de" />
</simple-license>

The <license-text> with lang="de" will be selected. This example uses the old method of determining the default locale. Starting with OOo 2.4 one should not use the default-license-id and license-id anymore.


Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages