goText Xml Language Format (v1.0.1) Documentation

Index:

Preamble

Version

Introduction

Audience

Xml Language Format

Xml Encoding Declaration

<languages>: the top level (outermost) tag

<language>: a group of localized messages for a specific language

<var>: assignment type variables to define localized messages in Variables

Uses of the Xml Language

The Standard Xml (Service) Phrasebook

Inside Xml Services

Appendix A: Format Version Changelog

Changes from v1.0 to v1.0.1

v1.0

Appendix B: The Author


Preamble

To understand this reference guide you should have:

Version

The Xml Language Format changes from times to times.

Everything written in this document applies only to version 1.0.1 of the format, that is to localized language files with xlv=”1.0.1”.

Introduction

The XML Language is a simple Xml text file with some special tags used to create localized messages (strings) used in Xml Services to return localized information to the user.

An Xml Service Engine will read and interpret the Xml Language tags and will automatically choose the correct string for the user language between the localizations available in the Xml Language file (or default to English localization if the user language can’t be found).

This means zero-effort localization for Xml Service writers!

A wider description of what an Xml Service Engine does (and what Xml Services are) can be found in the Xml Service Format documentation.

Audience

This technical document is targeted to people who want to write or modify Xml Services.

If you are novice to the Xml Services development you are suggested to read this document along with some existing Xml Service file opened in your favourite text (or xml) editor, and also read the Xml Service Format documentation.

If you have already wrote some Xml Service in the past you’ll find a complete reference to Xml Language files.


Xml Language Format

All Xml Service tags can be logically grouped in the following areas:

  1. XML Encoding Declaration
  2. <languages>: the top level (outermost) tag

  1. Xml Encoding Declaration

This part is optional (even if strongly recommended), and is the standard XML Encoding Declaration.

It is a text like the following one:

<?xml version="1.0" encoding="windows-1252"?>

and it is used to describe what character your text/XML editor is using to save your file.

If you don’t know what does this mean you should not write this special tag..anyway if you use Windows almost probably your editor will save the file in “windows-1252” encoding, while if you are using Linux or any other Unix like environment the editor will almost probably save the file with “UTF-8” encoding.

Note: This is quite important if you want to write string with non-ASCII characters or special chars (like: à, ò, æ...) inside the localized variables!!

  1. <languages>: the top level (outermost) tag

The <languages> tag is the top level tag and contains all other tags.

It also supports some mandatory attributes that inform the Xml Service Engine on what format version this Language file is using.

This is the <languages> tag with all possible attributes and their data type. Mandatory ones are bold:

<languages xlv="VERSION" revision="INTEGER" >

(..)

</languages>

Attributes description and use:

Attribute

Type

Description and values

xlv

VERSION

goText "Xml Language Format Version" number, as described in this document.
Changes to the xml specifications that break backward compatibility will have a new version number.

revision

INTEGER

Revision of the language file (starting with “1”), used by Xml Service Engines to check if there are updates to the file itself.

It should be updated every time you add some new localized variable to the file, or when some major misspelling is corrected in existing localized variables.

<language>: a group of localized messages for a specific language

The <languages> tag contains one or more <language> tag, one for each language supported.

<languages xlv="VERSION" revision="INTEGER" >

  <language code="STRING" name="STRING"> 

      <var name="VARNAME" value="STRING" />

        (..)

  </language>

  (..)

</languages>

<language> tag attributes description and use:

Attribute

Type

Description and values

code

STRING

Two letter code of this localization.

Example: “en”.

name

STRING

The user-friendly name of the language.

Example: “English”.

The <language> tag uses <var> tag of the assignment type to specify the localized messages.

<var>: assignment type variables to define localized messages in Variables

This tag defines a named variable that can be used inside the Xml Services: its name will be replaced with the localized message defined in this tag.

<var name="VARNAME" value="STRING" />

Attribute

Type

Description and values

name

VARNAME

The name you want to give to the variable.
It must start with a dollar symbol, and can only contain alphanumeric chars without spaces or special characters (that is only letters from "a" to "z", numbers, only symbol allowed is the underscore "_").

While not mandatory, you should start localized variable names with “$L_” (dollar + uppercase el letter + underscore symbol), so that they can be distinguished from general purpose variables defined in Xml Services.

Note: A valid name is "$L_error_example", while a wrong name is "this L is an-error"

value

STRING

The localized message string.

Note for those who already know Xml Service Variables: this is a variable of the Assigned type.


Uses of the Xml Language

The Standard Xml (Service) Phrasebook

One use of the Xml Language format is the Standard Xml Services Phrasebook (found on our SVN server with the name services_phrasebook.xml): this file contains a group of localized variables in many languages, with the most commonly used messages in all Xml Services.

The Standard Xml (Service) Phrasebook is always supported in all Xml Service Engines: this means that all variables defined in the Phrasebook can be used in all Xml Services by simply writing the name of the desired variable in the service.

That is, Xml Service developer have access to a zero-effort localization library for their services!

Inside Xml Services

When there is the need to localize a message that is specific to some service (eg: service description, non standard configuration field, etc..) it is possible to “embed” the Xml Language inside an Xml Service.

This is simply done by writing the <languages> (and its child tags) as a child tag of the <service> one inside the Xml Service file: please refer to the Xml Services Format documentation for more info.

Note: the xml encoding declaration of the Xml Language when defined inside a Xml Service file must be omitted, and the one global to the Xml Service file will be used.


Appendix A: Format Version Changelog

This appendix highlights the main changes between format version updates. This is helpful for software developers, and also to Xml Service writers who need to update their services to the latest format version.

Changes from v1.0 to v1.0.1

v1.0


Appendix B: The Author

This document has been written by Fulvio Sciarretta, known as Zydio on the goText Project.

Zydio is a developer of the goText Project from the late 2006, and co-admin from the 2007, and the mind and hands behind the goText++ project (goText++ Desk!) and the creator of the Xml Language (and Service) Format described in this document.