Localization/Translation FAQ
-
+ (2007-2018)
+
by Ran Rutenberg, Pavel Sanda, Michael Gerz
- February 2007
-This file is mainly intended for those who have no or little experience using
-.po files, but want to contribute by translating the LyX interface into their
-native language.
+PART I - Interface translation
+------------------------------
+
+This file is mainly intended for those who have no or little experience using
+.po files, but want to contribute by translating the LyX interface (i.e. menu
+and dialog items, console messages) into their native language.
1) WHERE DO I START?
-The file you need to edit it an xx.po file where xx stands for your language's
-two letter code. German would be for example de.po and Polish pl.po. For a list
-of country codes look at:
+The file you need to edit is an xx.po file where xx stands for your language's
+two letter code. For a list of language codes look at:
- http://www.gnu.org/software/gettext/manual/html_mono/gettext.html#SEC222
+ https://www.gnu.org/software/gettext/manual/html_mono/gettext.html#Language-Codes
-If you want to start from scratch than you should obtain a copy of the lyx.pot
-file.
+If you want to start from scratch then you should obtain a copy of the lyx.pot
+and name it after your language. German would be for example de.po and Polish
+pl.po. This file is generated in the "po" directory of the source tree during
+the compilation.
+
+There are basically two source trees you can start to work with - trunk
+(development version) and branch (stable version). Unless the development
+version is shortly before release it is better to start your translating
+work on the stable version. If you have no idea how to get those trees you
+can follow https://www.lyx.org/HowToUseGIT page.
2) HOW DO I EDIT PO FILES?
-PO files can be edited with every text editor available for your system (e.g.
-VIM, NotePad etc.). Yet another option is to use a specialized editor for .po
-files. You can e.g. use the editors "poEdit" or "jEdit", Linux users can
-additionally use e.g. "kbabel". Using these editors usually makes things easier
+PO files can be edited with any text editor available for your system (e.g.
+Vim, jEdit etc.). Yet another option is to use a specialized editor for .po
+files. You can e.g. use the editor "Poedit", Linux users can
+additionally use e.g. "Lokalize". Using these editors usually makes things easier
as they have many tools to assist the translator.
+If you use Poedit, please uncheck in its settings the option to break lines after
+80 characters.
3) WHAT DO I NEED TO TRANSLATE?
-If your using a simple text editor you should translate the strings that appear
-in the msgid line and write the translation into the msgstr line. Note that a
-"#, fuzzy" line is just a hint for translation from compiler - in order to get
-the translation of the current item working you have to delete this line. It is
-recommended that you would take a look at another .po file - that way you can
-get an idea of what to do. If your using a specialized po editor then you will
-see in it the untranslated strings and a place to write your translation for
-them.
+If you are using a simple text editor you should translate the strings that
+appear in the msgid line and write the translation into the msgstr line. Note
+that a "#, fuzzy" line is just a hint for translation from compiler - in order
+to get the translation of the current item working you have to delete this
+line. It is recommended that you take a look at another .po file - that way you
+can get an idea of what to do. If you are using a specialized po editor
+then you will see in it the untranslated strings and a place to write your
+translation for them.
-4) WHAT SHOULD I DO WITH THE '&', '|', '$, AND '%' CHARACTERS?
+4) WHAT SHOULD I DO WITH THE '&', '|', '$, '%' {} AND [[]] CHARACTERS?
'&' stands for underlined characters (shortcut) in dialog boxes.
'|' stands for underlined characters in menus.
-These chars should be somehow used in your translations, however you'll have to
-invent your own working shortcuts for dialog and menu entries and resolve
-possible conflicts of the same shortcut chars in one menu...
+These chars should be somehow used in your translations, however you'll have to
+invent your own working shortcuts for dialog and menu entries and resolve
+possible conflicts of the same shortcut chars in one menu...
+
+Note also that there are already used global shortcuts (such as p k x c m s a)
+and you should avoid using these characters for first-level menu shortcuts.
-'$' and '%' are usually used as handlers for formatting or variables to be
-inserted into the strings. Character sequences like %1$s or %1$d MUST also
-appear in your translations! Please take them exactly as they are or you may
+'$' and '%' are usually used as handlers for formatting or variables to be
+inserted into the strings. Character sequences like %1$s or %1$d MUST also
+appear in your translations! Please take them exactly as they are or you may
experience crashes when running LyX.
+[[Context]] is used to distinguish otherwise identical strings, which could
+have different translations depending on the Context. It can also be used to
+indicate what is substituted for a placeholder. [[Context]] appears only in
+msgid string and should not be repeated in the translated version.
+
+{} refer to counters and must not be translated. An example would be:
+msgid "Algorithm \\arabic{theorem}"
+msgstr "Algoritmus \\arabic{theorem}"
+
5) WHAT IS pocheck.pl AND HOW DO I USE IT?
-This is a small script located in the "po" directory of the source that helps
-you find common errors in your translation. In order to use this script you have
-to have the script language Perl installed.
+This is a small script located in the "po" directory of the source that helps
+you find common errors in your translation. In order to use this script you
+need the script language Perl installed.
+Run ./pocheck.pl -h to see all possible switches.
6) HOW CAN I TEST MY TRANSLATION?
-In order to test your translation you need to obtain the LyX sources (from the
-SVN repository) and replace the existing .po with yours. Afterwards, you should
-compile and install LyX (check the INSTALL file for your OS). If you don't
-install LyX it won't work. For running LyX with your translation, use the
-appropriate LANG variable:
+In order to test your translation you need to obtain the LyX sources
+(from the git repository) and replace the existing .po with yours.
+Afterwards, you should compile and optionally install LyX (check the
+INSTALL file for your OS). Note that, as of LyX 2.1, it is not
+necessary anymore to install anything.
+
+In order to run LyX with your translation, change the current language
+in Preferences dialog or use the appropriate LANG variable:
On Linux: LANG=xx_CC lyx
On Windows, you need to change the lyx.bat file and write: set LANG=xx_CC
-xx stands for your language code. CC stands for your country code. So to get,
+xx stands for your language code. CC stands for your country code. So to get,
e.g., Czech, the code is "cs_CZ".
-7) REFERENCES
+Another possibility is to use the Preferences dialog to set LyX UI to
+use your language. Note that, as of LyX 2.2, a newly introduced
+language will not appear in the languages combox unless it corresponds
+to an entry of the lib/languages file that has a "HasGuiSupport true"
+property. See this file for more details.
+
+The most comfortable way to see your updated translation while
+editing, is running (in linux) "make xx.gmo" in the po directory to
+compile updated xx.po translation and then run LyX.
+
+For advanced users - if you want to remerge your files against current source:
+
+- on Linux: execute the command: make update-po
+- on Windows: if you compile LyX in install mode, the po files are automatically
+ updated and output to the folder <compilation output folder>\po
+ Another option is to build the target "update-po" in MSVC.
+
+
+7) HOW TO CONTRIBUTE MY WORK?
+
+Send your edited xx.po file to po-updates@lyx.org.
+
+Also you can check https://www.lyx.org/trac/browser/lyxgit/?rev=master to track
+changes or watch updates.
+
+
+8) SHALL ALL THE UNUSED STRINGS AT THE BOTTOM OF .PO FILE BE REMOVED,
+ OR SHALL THEY STAY?
+
+As you wish. They can be reused for generating fuzzy hints when completely
+new strings appear, no other function.
+
+
+9) REFERENCES
+
+For a basic idea of how the translation works, you can look at
+
+ https://en.wikipedia.org/wiki/Gettext
+
+For detailed reference (including a full list of country and language codes),
+have a look at
+
+ https://www.gnu.org/software/gettext/manual/gettext.html
+
+
+Consider subscribing to the documentation list, lyx-docs@lists.lyx.org (rather
+silent), or the developer's mailing list, lyx-devel@lists.lyx.org (high
+volume).
+
+
+
+PART II - Translation of Math environments and Floats in the final output
+-------------------------------------------------------------------------
+
+As of 2.0 LyX allows automatic translation in tex/dvi/ps/pdf output for math
+environment strings (and some floats) which are not automatically translated via
+babel package to the localized form. For example the environment "Exercise"
+becomes "Aufgabe" in the output of the documents with language set to German.
+
+These translations are taken from the previously translated .po file before the
+final major LyX release (e.g. 2.0.0) and are fixed for all next minor releases
+(e.g. 2.0.x) in order to have fixed output of LyX documents.
+
+The current translation for your language can be found in the file
+lib/layouttranslations. An easy way to check many of the translations is to
+simply load lib/examples/localization_test.lyx in LyX and read its
+instructions.
-For some basic idea on how the translation works, you can look at
+The problematic strings can be then fixed in the .po file. For inspiration the
+typical places in .po files, where to fix the translation, can be seen on the
+following commit: https://www.lyx.org/trac/changeset/38169.
- http://en.wikipedia.org/wiki/Gettext
+If you need to manually regenerate the layouttranslations file from .po files
+- Under Linux: If using autotools, execute the command
+ `make ../lib/layouttranslations'
+ in the po directory. If using CMake, execute the command
+ `make layouttranslations1'
+ in the build directory.
+ The Python polib library is needed for building the output file.
+- Under Windows:
+ 1. install the Python extensions "polib". To do this,
+ 1.1 open a commen line prompt in the folder where you find the file "pip.exe"
+ withing the python installation folder.
+ 1.2 execute the command
+ pip install polib
+ 2. close the command prompt and open the file "lyx.sln" with MSVC. You find
+ file in the compilation result folder you set for LyX
+ 3. right click in MSVC on the target "layouttranslations1" and choose "Rebuild"
-For detailed reference, have a look at
+Optionally - to quickly check whether some new translatable strings appeared
+for your language you can always check ../lib/layouttranslations.review.
- http://www.gnu.org/software/gettext/manual/gettext.html
+Q: Running make ../lib/layouttranslations returns with just saying
+ ../lib/layouttranslations is up to date.
+A: To force regerenation, use something like (XX is your language)
+ make -W XX.po ../lib/layouttranslations
projects / lyx.git / blobdiff