Internationalization

This page is outdated (October 2019).

GUI

The Octave GUI has already been translated in many languages.

Help text

While this is a noble purpose it has received very little attention. Translating the GUI is much simpler but to translate the documentation and help text of each function is a massive ammount of work. Not only that, the gain from such work will be very small since Octave users are very likely to be confortable in the english language. Remember that function names, such as size() are in english and of course, those cannot change.

Octave Forge

There is no one still working on this translation project but all the sources and previous translations are available.

Octave should be available in your own language. The original authors, being primarily English speakers, are unable to provide this service. Instead it is up to you, the user, to help translate Octave documentation into your language. The Octave translation project provides the infrastructure to do so.

The idea

For each function in Octave, and each chapter in the Octave manual, we will have a corresponding document in the ZZ language tree containing the translation of this document. The translation provides a function help, aide, ajuda, etc., which searches for fn.ZZ and displays that instead of the original file help.

We want to be able to tell if translated help is out of date with the current text in an Octave function. The plan is to generate an md5 sum for the raw Octave help string (currently extracted from DOCSTRINGS) and store that with the translated file. When the user asks for help on the function, the help command will look for a localized help string in the search path (e.g., file_in_loadpath ("filter.pt") for the Portuguese translation of filter), extract the Octave help string, compute its md5 sum and compare it to the md5 sum stored in the translated file. If it differs the user will be warned that the translated help is out of date and will be given instructions to get the original help.

When the base text changes, translators need to know exactly how it changed. For this reason we are storing the original text for the translation in the language source tree and updating it whenever Octave is released. We will store the revision number of the base file in the translated file. The translator can then use e.g., svn diff -r4145 filter in the base directory to find out how filter has changed between version 4145 and the current version.

Translators can also add their name and email to the translated file.

The top line will look something like:

md5="d52f61a8b12616e7b99f7cd5ecbf18fb";rev="1.1";by="I.M. Translator <im.translator@gmail.com>"

Downloading and installing

The translations themselves are available as standard Octave packages, and can be downloaded from the packages page.

Contributing your own translations

If you want to help with the Octave translation project, the tree is now available at source-forge.

1. You first need to become an Octave-Forge developer
2. Check out the current Octave-Forge tree that contains the language sources:

   $ cd working_directory

   $ svn co https://octave.svn.sourceforge.net/svnroot/octave/trunk/octave-forge

3. Language/admin will contain administration tools to identify what needs to be translated, while language/base contains the strings which need to be translated.

To create a new language translation in the octave-forge/language directory, you need to:

1. Choose a language extension. In general a standard language extension such as fr, jp or pt should be used. Call the chosen extension <ext>.
2. Copy the base/template directory to <ext>.
3. Choose a name meaning "help" in your language and move the <ext>/src/help.cc to a file with this name. For example for French aide.cc is an appropriate name.
4. Edit <ext>/Makefile and modify EXT. This should, but is not required to be <ext>. The translated files under <ext>/help must have this suffix.
5. Edit <ext>/DESCRIPTION and modify the author, maintainer, etc fields
6. Edit the new help file and alter the macros and PKG_ADD directive at the top of the file. In particular LANG_EXT must match EXT. All of the macros must be translated to the new language
7. Remove the files under <ext>/help/octave/ as these are examples
8. Translations of Octave core functions should be under <ext>/help/octave, whereas translations of help strings from Octave-Forge packages should be under <ext>/help/<package>

Some things to look out for when translating:

• Do not translate anything that have an * or an @ until you are certain what you are doing. texinfo use these for special purposes.
• Search for special characters (diacritical marks) in your language, and where needed use the texinfo versions of these. For example, in Portuguese these are:

           @'a @'A @`a @`A @'e @'E @`e @`E @'I
           @`o @`O @'u @'U @`u @`U @,{c} @,{C}
           @~o @~O @"u @"U

The scripts under admin/ can be used to help in maintaining the translations. In particular octlang allows the maintanence of the translations.

After each translation, run octlang tag function in the root directory of your translation. This locates the file file.EXT corresponding to the translation of the functaion, computes the md5 sum in the base directory and tags the top line of the translation with

mdf="$MD5SUM";rev="$REV";by="$OCTAVE_TRANSLATOR"

where MD5SUM and REV are computed by the script and OCTAVE_TRANSLATOR is exported from the shell.

Maintaining your translations

As Octave evolves you will need to keep your translations up to date. The script admin/octlang can help you:

octlang missing

walk the current subtree listing all translations which are missing.

octlang updated

walk the current subtree listing all translations which are out of date.

octlang diff function

list differences between the original text which was translated and the current text in base.

octlang tag function

tag function.ZZ as up to date, marking the header with the current md5 sum and version number from base.

These commands should be run in the base directory of your package and admin/ directory should be on your path or octlang should be called explicitly.

Updating base

Once per Octave release, somebody will need to update the help messages stored in the base translation tree.

1. Download and unbundle the latest 3.0.xx stable release from www.octave.org
2. Create src/DOCSTRINGS and scripts/DOCSTRINGS using:

   cd octave-3.0.xx

   ./configure

   (cd src && make omit_deps=1 DOCSTRINGS)

   (cd scripts && make DOCSTRINGS)

3. Update base docs using:

   export OCTAVE_ROOT=~/Downloads/octave-3.0.xx

   cd octave-forge/language/base/help/octave

   ../../../admin/split_docstrings $OCTAVE_ROOT/src/DOCSTRINGS

   ../../../admin/split_docstrings $OCTAVE_ROOT/scripts/DOCSTRINGS

4. Compare new base docs to those on the server:

   svn status -u

   Those that have been updated since the last release will be marked M. Those that are new will be marked ?. You won't be able to tell if any have been deleted.

5. Inform server of new docs:

   svn add ...

   where ... is the list of names marked by ?.

6. Update server with new base docs:

   svn commit