Constructing the XML file with localization

The obligatory part

The absolutely minimum of what the XML file with localization should contain is shown below:

<?xml version="1.0" encoding="utf-8"?>
<Localization xmlns="XMLocalizator">
  <Language>English</Language>
  <Phrases>
    <Phrase Id="1" Key="Button"></Phrase>
  </Phrases>
</Localization>
  1. Declaration of XML format
    • XML version is 1.0
    • Encoding is utf-8, and the file itself should be in this format as well.
  2. The root element is titled Localization and contains declaration of the XMLocalizator namespace.
  3. The first child element is titled Language and contains name of the language that this document is localizing to.
  4. The second child element is titled Phrases and it's a collection of Phrase elements. It should contains at least one of them.
  5. The Phrase element contains attributes:
    • Id, which is a positive integer number.
    • Key, which is a string.

Additional information

Beside Language, you can insert to the XML file various information. All are listed below:
  • Language - as mentioned, name of the language that this document is localizing to
  • LanguageTag - shortcut name of the language, in most cases it would be the IETF Language Tag , or other
  • Author - name of this localization's author
  • Application - name of the application which this localization is dedicated for
  • ApplicationVersion - version of the application which this localization is dedicated for
  • LocalizationVersion - version of this localization
  • CustomData - some custom information that you might want to include
And here is how to extend the previous example with them:

<?xml version="1.0" encoding="utf-8"?>
<Localization xmlns="XMLocalizator">
  <Language>English</Language>
  <LanguageTag>en-US</LanguageTag>
  <Author>John Smith</Author>
  <Application>XMLocalizator Demo</Application>
  <ApplicationVersion>1.0</ApplicationVersion>
  <LocalizationVersion>1.0</LocalizationVersion>
  <CustomData>This is the reference localization.</CustomData>
  <Phrases>
    <Phrase Id="1" Key="Button"></Phrase>
  </Phrases>
</Localization>

All of these elements are string values, so you can freely add letters to- for example- ApplicationVersion, and it's still correct:

<ApplicationVersion>1.0 pre-alpha</ApplicationVersion>

Phrases

The single Phrase element is built due to the template:

<Phrase Id="1000" Key="Key phrase">Localized phrase</Phrase>

You can obtain the value of the phrase (in example above it's "Localized phrase") by calling it by Id, or by the Key. This is why both of them need to be unique in the entire collection.

For example, this is wrong (duplication of Id):

<Phrases>
    <Phrase Id="1" Key="Button"></Phrase>
    <Phrase Id="1" Key="Title"></Phrase>
</Phrases>
as well as this (duplication of Key):

<Phrases>
    <Phrase Id="1" Key="Button"></Phrase>
    <Phrase Id="2" Key="Button"></Phrase>
</Phrases>

If the phrase's value is empty in the XML file, XMLocalizator will take the key instead. Thanks to this, there is no need to have the same data in two places in the file with reference language. So remember that this:

<Phrase Id="1" Key="Some key phrase"></Phrase>
is equivalent to this:

<Phrase Id="1" Key="Some key phrase">Some key phrase</Phrase>

Example of the proper localization files

English.xml
<?xml version="1.0" encoding="utf-8"?>
<Localization xmlns="XMLocalizator">
  <Language>English</Language>
  <LanguageTag>en-US</LanguageTag>
  <Author>John Smith</Author>
  <Application>XMLocalizator Demo</Application>
  <ApplicationVersion>1.0</ApplicationVersion>
  <LocalizationVersion>1.0</LocalizationVersion>
  <CustomData>This is the reference localization.</CustomData>
  <Phrases>
    <Phrase Id="1" Key="Button"></Phrase>
    <Phrase Id="2" Key="Title"></Phrase>
    <Phrase Id="3" Key="Menu"></Phrase>
    <Phrase Id="4" Key="Content"></Phrase>
  </Phrases>
</Localization>

Polish.xml
<?xml version="1.0" encoding="utf-8"?>
<Localization xmlns="XMLocalizator">
  <Language>Polski</Language>
  <LanguageTag>pl-PL</LanguageTag>
  <Author>Jan Kowalski</Author>
  <Application>XMLocalizator Demo</Application>
  <ApplicationVersion>1.0</ApplicationVersion>
  <LocalizationVersion>1.0</LocalizationVersion>
  <CustomData>Autorskie tłumaczenie.</CustomData>
  <Phrases>
    <Phrase Id="1" Key="Button">Przycisk</Phrase>
    <Phrase Id="2" Key="Title">Tytuł</Phrase>
    <Phrase Id="3" Key="Menu"></Phrase>
    <Phrase Id="4" Key="Content">Treść</Phrase>
  </Phrases>
</Localization>

Creating localization file from the code

To obtain the same content as in Polish.xml in the example above, do:

XMLocalizator.XmlElements.Localization polish = new XMLocalizator.XmlElements.Localization();
polish.Language = "Polski";
polish.LanguageTag = "pl-PL";
polish.Author = "Jan Kowalski";
polish.Application = "XMLocalizator Demo";
polish.ApplicationVersion = "1.0";
polish.LocalizationVersion = "1.0";
polish.CustomData = "Autorskie tłumaczenie";

XMLocalizator.XmlElements.Phrase phrase1 = new XMLocalizator.XmlElements.Phrase();
phrase1.Id = 1;
phrase1.Key = "Button";
phrase1.Value = "Przycisk";

polish.Phrases.Add(phrase1);

// you can use the constructors as well:
polish.Phrases.Add( XMLocalizator.XmlElements.Phrase(2, "Title", "Tytuł") );
polish.Phrases.Add( XMLocalizator.XmlElements.Phrase(3, "Menu") );
polish.Phrases.Add( XMLocalizator.XmlElements.Phrase(4, "Content", "Treść") );

The final action is serializing the Localization object we just prepared. For your convenience there is SaveAsXml function in the Localization class. Using it is the simpliest possible way:

polish.SaveAsXml(@"d:\CustomApp\Languages\Polish.xml");

Last edited Mar 20, 2011 at 6:59 PM by lkrawczyk, version 14

Comments

No comments yet.