Difference between revisions of "Documentation/DevGuide/Extensions/Localized XML Elements"
From Apache OpenOffice Wiki
< Documentation | DevGuide
m |
|||
| Line 11: | Line 11: | ||
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 {{AOo}}. Localized data is used for | 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 {{AOo}}. Localized data is used for | ||
| − | * License files (simple license, since | + | * License files (simple license, since OpenOffice.org 2.0.4) |
| − | * Publisher name and URL for publisher homepage (since | + | * Publisher name and URL for publisher homepage (since OpenOffice.org 2.4) |
| − | * URL for release notes (since | + | * URL for release notes (since OpenOffice.org 2.4) |
Localized data is typically expressed in this format: | Localized data is typically expressed in this format: | ||
| − | < | + | <syntaxhighlight lang="xml"> |
<parent> | <parent> | ||
<child lang="en-US" /> | <child lang="en-US" /> | ||
<child lang="en-GB" /> | <child lang="en-GB" /> | ||
</parent> | </parent> | ||
| − | </ | + | </syntaxhighlight> |
The children of <parent> have all a lang attribute, which have a language string according to RFC 3066. The following restrictions currently apply: | The children of <parent> have all a lang attribute, which have a language string according to RFC 3066. The following restrictions currently apply: | ||
| Line 45: | Line 45: | ||
*All children have a lang attribute | *All children have a lang attribute | ||
| − | Output of the | + | Output of the algorithm: |
* A child element (immediate child) of parent. | * A child element (immediate child) of parent. | ||
| Line 58: | Line 58: | ||
# The first child element will be selected as output. | # The first child element will be selected as output. | ||
| − | Please note that before | + | Please note that before OpenOffice.org 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 using the new "style" when providing a new version of an extension, where the previous version used the old "style". |
| Line 64: | Line 64: | ||
Example 1: | Example 1: | ||
| − | < | + | <syntaxhighlight lang="xml"> |
<simple-license accept-by="user" > | <simple-license accept-by="user" > | ||
<license-text xlink:href="lic_en" lang="en" /> | <license-text xlink:href="lic_en" lang="en" /> | ||
| Line 71: | Line 71: | ||
<license-text xlink:href="lic_en-US-region1" lang="en-US-region1" /> | <license-text xlink:href="lic_en-US-region1" lang="en-US-region1" /> | ||
</simple-license> | </simple-license> | ||
| − | </ | + | </syntaxhighlight> |
The <code><license-text></code> with lang=”en-US” will be selected. This is a perfect match. | The <code><license-text></code> with lang=”en-US” will be selected. This is a perfect match. | ||
| Line 77: | Line 77: | ||
Example 2: | Example 2: | ||
| − | < | + | <syntaxhighlight lang="xml"> |
<simple-license accept-by="user" > | <simple-license accept-by="user" > | ||
<license-text xlink:href="lic_en" lang="en" /> | <license-text xlink:href="lic_en" lang="en" /> | ||
| Line 85: | Line 85: | ||
<license-text xlink:href="lic_en-US-region2" lang="en-US-region2" /> | <license-text xlink:href="lic_en-US-region2" lang="en-US-region2" /> | ||
</simple-license> | </simple-license> | ||
| − | </ | + | </syntaxhighlight> |
The <code><license-text></code> 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. | The <code><license-text></code> 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. | ||
| Line 91: | Line 91: | ||
Example 3: | Example 3: | ||
| − | < | + | <syntaxhighlight lang="xml"> |
<simple-license accept-by="user" > | <simple-license accept-by="user" > | ||
<license-text xlink:href="lic_en" lang="en" /> | <license-text xlink:href="lic_en" lang="en" /> | ||
| Line 98: | Line 98: | ||
<license-text xlink:href="lic_en-region2" lang="en-region2" /> | <license-text xlink:href="lic_en-region2" lang="en-region2" /> | ||
</simple-license> | </simple-license> | ||
| − | </ | + | </syntaxhighlight> |
The <code><license-text></code> 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". | The <code><license-text></code> 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". | ||
| Line 104: | Line 104: | ||
Example 4: | Example 4: | ||
| − | < | + | <syntaxhighlight lang="xml"> |
<simple-license accept-by="user"> | <simple-license accept-by="user"> | ||
<license-text xlink:href="lic_de" lang="de" /> | <license-text xlink:href="lic_de" lang="de" /> | ||
| Line 111: | Line 111: | ||
<license-text xlink:href="lic_en-region2" lang="en-region2" /> | <license-text xlink:href="lic_en-region2" lang="en-region2" /> | ||
</simple-license> | </simple-license> | ||
| − | </ | + | </syntaxhighlight> |
The <code><license-text></code> 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". | The <code><license-text></code> 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". | ||
| Line 117: | Line 117: | ||
Example 5: | Example 5: | ||
| − | < | + | <syntaxhighlight lang="xml"> |
<simple-license accept-by="user" > | <simple-license accept-by="user" > | ||
<license-text xlink:href="lic_de" lang="de" /> | <license-text xlink:href="lic_de" lang="de" /> | ||
| Line 123: | Line 123: | ||
<license-text xlink:href="lic_fr" lang="fr" /> | <license-text xlink:href="lic_fr" lang="fr" /> | ||
</simple-license> | </simple-license> | ||
| − | </ | + | </syntaxhighlight> |
The <code><license-text></code> 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. | The <code><license-text></code> 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: | Example 6: | ||
| − | < | + | <syntaxhighlight lang="xml"> |
<simple-license accept-by="user" default-license-id="de" > | <simple-license accept-by="user" default-license-id="de" > | ||
<license-text xlink:href="lic_es" lang="es" /> | <license-text xlink:href="lic_es" lang="es" /> | ||
| Line 134: | Line 134: | ||
<license-text xlink:href="lic_de" lang="de" license-id="de" /> | <license-text xlink:href="lic_de" lang="de" license-id="de" /> | ||
</simple-license> | </simple-license> | ||
| − | </ | + | </syntaxhighlight> |
| − | The <license-text> with lang="de" will be selected. This example uses the old method of determining the default locale. Starting with | + | The <license-text> with lang="de" will be selected. This example uses the old method of determining the default locale. Starting with OpenOffice.org 2.4 one should not use the default-license-id and license-id anymore. |
Latest revision as of 16:03, 2 January 2021
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 Apache OpenOffice. Localized data is used for
- License files (simple license, since OpenOffice.org 2.0.4)
- Publisher name and URL for publisher homepage (since OpenOffice.org 2.4)
- URL for release notes (since OpenOffice.org 2.4)
Localized data is typically expressed 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:
- Apache OpenOffice uses only lang-country
- the language string can only have one variant, for example de-DE-mitte
- Apache OpenOffice uses uppercase letters for the country. The language strings must also use uppercase letters for the country. That is, the comparison between the Apache OpenOffice's locale and the locale strings of the elements is case-sensitive.
Let's assume that Apache OpenOffice 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 probably prefer en-NZ over de. The algorithm tries to find a locale which 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 algorithm:
- A child element (immediate child) of parent.
Algorithm:
- 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.
- 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.
- 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
langattribute with the values “en-US-north”, “en-US-south”, etc. The first child element with a matchinglangattribute is selected as output. If there is a match then we are done. - 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.
- 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
langattribute with the values “en-GB”,“en-GB-north”, etc. The first child element with a matchinglangattributed is selected as output. If there is a match then we are done. - The first child element will be selected as output.
Please note that before OpenOffice.org 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 using the new "style" when providing a new version of an extension, 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 Apache OpenOffice 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 OpenOffice.org 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). |
