ReadMe.txt | Au3Text v1.0
09-09-2012 | dany

                            AU3Text 1.0

An UDF to ease the internationalization of AutoIt 3 scripts and programs.

Version:                    1.0
License:                    Open Source
Language:                   English
Author:                     Dany
Link:                       http://www.autoitscript.com/forum/topic/144037-au3text-internationalization-udf/

Loosely based on gettext: http://www.gnu.org/software/gettext/manual/gettext.html

Messages are stored in an INI file. AU3Text is initialized with _AU3Text_BindTextSection
or _AU3Text_TextSection. If no language identifier in ISO 639-1 ('en', 'nl' etc.)
or ISO 639-2 ('eng', 'nld' etc.) format is given, then the current OS locale is
retrieved with _GetLocale(). The path of the language file is constructed from
the locale as follows:
$AU3TEXT_I18NDIR = @ScriptDir & '\I18n'
$AU3TEXT_I18NDIR & (@ScriptName without extension) & .(locale) & .lng
AU3Text provides a fully portable implementation where the following directory
structure is expected:
    MyScript.au3
    I18n\MyScript.en.lng
    I18n\MyScript.nl.lng
    MyCompiledScript.exe
    I18n\MyCompiledScript.en.lng
    I18n\MyCompiledScript.nl.lng
This means that multiple scripts and their respective language files can exist
side by side without conflicts.

AU3Text can be used in two ways. In all functions the INI key where the message
is stored is the last argument and always optional. If a string is passed, this
is used to look up the message. However, if the key isn't given, a key is generated
by calculating the MD5 hash of the message. This 'MD5 mode' closely mimicks the
implementation of gettext, but does create a few drawbacks. For one, the language
files arn't really human-friendly, although numeric alternatives (e.g. 1003, 1028
etc.) arn't either. Also, an update on a string means the MD5 will also change.
Then again, an update will usually overwrite existing language files anyway...
A plus however is that the programmer doesn't need to worry about maintaining
unique identifiers, AU3Text does this on-the-fly.

To create multi-line messages use @CRLF or \n like this:
'first line@CRLFsecond line'
'first line\nsecond line'
Expansion of \n, \r, \r\n and \t is supported, as is the expansion of all AutoIt
macro's.

To literally print @ macro's and meta-characters like \n in a message simply
use @@ or \\ as an escape sequence.

If a language file does not exist and $AU3Text_fCreateLanguageFiles = True, all
non-existent messages are written to a new file. This will mix foreign languages
with the language used in the source if a language file already exists, but that
makes it easier to spot missed or new messages that are in need of translating.
It also makes it easier to generate language files in new applications. Drawback
is that the keys are not sorted, which can become quite a hassle to maintain
with large applications.

Messages are stored internally in an array. Searching this array is faster by
about factor ten compared to continuously reading single values from the file
(tested with a GUI and a thousand messages).

Files:
ReadMe.txt                  This file.
AU3Text-HowTo.txt           Step by step instructions to convert programs for
                            internationalization with AutoIt.
AU3Text-Demo.au3            AU3Text demo.
AU3Text-Demo-Config.au3     AU3Text demo configuration file.
AU3Text-Extractor.au3       Source file for command line utility to extract
                            AU3Text messages from scripts. You'll need to compile
                            this script before you can use it.
                            This is BETA software! Report all bugs etc. at the
                            forum (link above).
Lib\AU3Text.au3             Main AU3Text library.
Lib\AU3TextGUI.au3          AU3Text GUI helpers.
Lib\AU3TextDev.au3          Additional developer functions.
Lib\Locale.au3              Locale functions. Originally based on guinness'
                            excellent _GetOSLanguage function, but has grown into
                            a full stand-alone UDF.
Lib\Ini.au3                 UTF-16 LE INI functions.
Lib\StringFormatEx.au3      Modified StringFormat function. See
                            http://www.autoitscript.com/forum/topic/139260-autoit-snippets/page__st__60#entry1010824
I18n\AU3Text-Demo.en.lng    English demo language file.
I18n\AU3Text-Demo.nl.lng    Dutch demo language file.
Res\AU3Text-Extractor.ico   Pic unrelated.

AU3Text-Extractor usage:
This will extract all AU3Text messages in MyScript.au3 and write them to
I18n\MyScript.nl.lng:
AU3Text-Extractor.exe MyScript.au3 nl
Ironically, AU3Text-Extractor is currently a perfect example of a localized
program... Once all error checks are in place and extracting is fully developed
and debugged, a GUI will be made and if possible, a simple editor component will
also be added.
