Difference between revisions of "Translation information"

From Inkscape Wiki
Jump to navigation Jump to search
(→‎Tutorial translations: Scislac is now doing the conversion to SVG)
m (→‎Submit finished work: Add in link to Marc's instructions - working as of Sept. 24)
 
(71 intermediate revisions by 18 users not shown)
Line 1: Line 1:
= Tutorial translations =
This page gathers useful information about translation.


Inkscape tutorial sources are in [[DocBook]] format, with illustrations in SVG. If you want to translate one or more tutorials, first download the [[DocBook]] source here:
== Links and docs ==


http://svn.sourceforge.net/viewcvs.cgi/inkscape/doc-docbook/trunk/
* '''[https://inkscape.org/contribute/translations/ How to contribute in translation]'''
* [https://inkscape.org/doc/devel/translations-statistics-master.html Translations statistics for master branch (development focus)]
* [https://inkscape.org/develop/inkscape-git/ Using Inkscape's repositories]
* [https://lists.inkscape.org/postorius/lists/inkscape-translator.lists.inkscape.org/ Subscribe to the translator mailing list]
* [https://lists.inkscape.org/hyperkitty/list/inkscape-translator@lists.inkscape.org/ Translator mailing list archives]
* [https://chat.inkscape.org/channel/team_translation Translator chat channel]
* [[Interface translation]]
* [[Documentation translation]]
* [[WebSite#Translations|Website translation]]


Each tutorial is in its own subdirectory. You need the *.xml file, for example basic/tutorial-basic.xml. Get it and simply replace all English text in it with the text in your language, preserving all XML markup. See README at that location for some notes on markup.
== PO translation files ==


* If there's already such a file in CVS, you can edit it instead :) If there's no xml file at the above location but there's a translation of this tutorial in SVG format (in share/tutorials in Inkscape distribution), you'll need to convert it to [[DocBook]] (and probably update). Conversion can be done simply by: select the text blocks of an SVG tutorial in Inkscape, Ctrl+C, and Ctrl+V in your text editor, then add the markup.
=== Add a new translation file ===


* Save your file as <original name>.<language suffix>.xml, for example basic/tutorial-basic.es.xml for Spanish.  
If the PO file for your language does not exist yet, then you must create it as a copy of the translation template. This template is a file whose name ends with .pot. It contains the strings to translate without any translation. Create a copy and put it to the right place (just see how other languages are managed).


* Do not use symbolic entities like &amp;aacute; (they're not defined in XML without a DTD). Instead use either numeric entities such as &amp;#225; or simply write your text in UTF-8.
=== Tools for translators ===


* Most illustrations don't need translations, so you leave the references to them from English XML intact. If however an illustration has some text that you want to translate, open the illustration file in Inkscape (e.g. basic/basic-f12.svg), edit it as needed, and save under a different name (e.g. basic/basic-f12-es.svg). Then change the filename reference in the XML source appropriately.
You can edit PO files from any plain text editor, since they are simple text files. However, many useful tools have been developed to provide a simple experience translating PO files.


* When finished, run [http://xmlsoft.org/xmllint.html xmllint] on your file to make sure it's well-formed.
Recommended:
* [https://poedit.net/ Poedit] (cross-platform);
* [https://userbase.kde.org/Lokalize Lokalize] (KDE).


* Send the file to Joshua Andler <scislac at users dot sf dot net>, and he'll convert it to SVG and HTML and upload it to SVN and the web site.
You might also try:
* Emacs's po-mode (contained in the gettext distribution; the version in po-utils is old);
* [https://wiki.gnome.org/action/show/Apps/Gedit gedit] — text editor for GNOME desktops, has a syntax highlight mode for PO file syntax;
* [http://virtaal.translatehouse.org/ Virtaal] — cross-platform PO editor that is clean, simple to use yet powerful;
* [https://wiki.gnome.org/Apps/Gtranslator Gtranslator] (GNOME).


* If after that you want to make any changes, download the file from the above location again, because it may have changed compared to the one you have.
And last but not least, [http://www.gnu.org/software/gettext/manual/ gettext] utils, which are installed on every Linux distribution. You can see a complete reference too from installed info pages by running the command:
<pre>
info gettext
</pre>


==Tools==
=== Update a translation file ===
* xml2po in gnome-doc-utils (http://ftp.gnome.org/pub/gnome/sources/gnome-doc-utils/)
* OmegaT - http://www.omegat.org/omegat/omegat_en/omegat.html
* Transolution - http://transolution.python-hosting.com/


= Interface translations =
If a translation file is already present for your language but the programmers have updated the template (.pot) since the translation was done, you need to sync the PO file with the template, especially for the new strings being added, but also for other info: position of the original string in the project, removing or marking obsolete strings, recognizing small string modifications…


If you're interested in helping with providing interface translation for Inkscape,
Some software offers the ability to automatically sync the translation file with the template, e.g. with Poedit you can use the menu option ‘Catalog > Update from POT file…’.
here are a few links to help you getting started:


    http://www.gtkmm.org/gtkmm2/docs/tutorial/html/ch20s03.html
GNU gettext also provides the command <code>msgmerge</code>. You can use it like this to update ''lt.po'' from ''inkscape.pot'':
    http://developer.gnome.org/projects/gtp/l10n-guide/
<pre>
    http://developer.gnome.org/projects/gtp/style-guides/
msgmerge -U lt.po inkscape.pot
    http://developer.gnome.org/doc/tutorials/gnome-i18n/developer.html
</pre>


Download the .po file for your language from here:
=== File format ===


    http://svn.sourceforge.net/viewcvs.py/inkscape/inkscape/trunk/po/
If you open a PO file with a text editor for the first time, you will find its syntax very simple. The PO format is a really simple format, which probably at least partly explains its success and widespread use. The format is basically a hash list consisting of msgid and msgstr pairs, with the msgid being the original English string and key, and the msgstr being the translated value of it. Below is an example of a message.


If a .po file for your language does not yet exist, then create one
<pre>
by copying the inkscape.pot file that gets generated when you run make
#: gedit/dialogs/gedit-plugin-program-location-dialog.c:78
in the codebase.
#: gedit/dialogs/program-location-dialog.glade2.h:2
msgid "Set program location..."
msgstr "Ställ in programplats..."
</pre>


Edit the file to add or correct translations of the English strings, and
In addition to the msgid and msgstr parts, a message usually also has lines starting with <code>#:</code> that tell what source files and what lines the string used as msgid was extracted from. These lines have no syntactic value. They are only there as a help for translators and developers to know where a message came from.
then upload your work via the [[SourceForge]] patch tracker:


    http://sourceforge.net/tracker/?func=add&group_id=93438&atid=604308
A message in a PO file can be in one of essentially three different states. The message can be translated, fuzzy, or untranslated. A message counts as translated as soon as the msgstr part of it is non-empty. In a similar manner, an untranslated message is one where the msgstr is empty. The fuzzy state is special and essentially means that there is a translation in the msgstr part, but that this translation is most likely not entirely correct, and that it thus needs manual attention by a translator. A message can become fuzzy in one of two ways:


(Check the Upload checkbox and add your file or patch.)
* The original string that the msgid represents was changed in the source code. A typo in the string may have been fixed or the string altered in some other way. The translator needs to check that the msgstr is still valid and make changes if necessary.
* A new string has been added to the source, and the string is similar (but not identical) to the msgid of an already existing, translated message. Then the msgstr of that message will be automatically reused for the new message, but the new message will also at the same time be marked fuzzy so that the translator knows there is some difference that he or she needs to adapt the translation to match.


=== A few important things to remember ===


* Some strings that can be ambiguous or having several meanings according to different contexts may have a context prefix: ‘Context|Ambiguous string’. In this case, give the translation for ‘Ambiguous string’ only; the ‘Context|’ part is just a not to translate indication.
* After translating a fuzzy string (one that is marked with a <code>", fuzzy"</code> comment), please remove its fuzzy tag — otherwise this translation will be discarded by the build process, meaning that this string will show up untranslated.
* Before publishing your work (after you have finished updating the PO file), please update the <code>"PO-Revision-Date"</code> and <code>"Last-Translator"</code> fields in the PO file header.


Here's how to make an absolutely up-to-date translation (in case the PO file in SVN is not up-to-date enough):
If you use a translation software, it may deal with the last two points for you automatically (check the settings).


1. update your local copy of Inkscape in the usual way: "svn update"
=== Verification ===
2. "./autogen.sh"
3. "./configure"
4. enter the "po" directory: "cd po"
5. generate the current PO template: "intltool-update --pot"
6. merge your existing translations into the new POT file (inkscape.pot):
    "msgmerge your_latest_PO_file inkscape.pot > new_PO_file"


Then you just need to complete the translations in the PO file that was
Before submitting your file to the project, you should make sure it is valid.
created in step 6.
* Make sure the file is encoded in UTF-8.
* Make sure it is a valid PO file and obtain some statistics about it: simply run <code>msgfmt --statistics -cv translation_file.po</code> from a command window.
* Make sure it is correctly formatted: run <code>check-markup translation_file.po</code> from a command window and verify it doesn't output any error message. The ‘check-markup’ Perl script can be found in the /po directory of Inkscape trunk.


If your translation software can compile PO files to .mo, it should detect any errors when you save your translations so you don't need to do any further verifications.


If you want to update ALL .po files in po/, cd there and run:
=== Programmers ===


make update-po
There is always one special message in each valid PO file: the PO file header. It is encoded with the msgid for the empty string (<code>""</code>) as the key, and the actual header values are in the msgstr part. This unfortunately means that if you mark an empty string for translation, you will get the entire PO file header back as the ‘translation’. In almost all cases this is probably not what you want. Hence, do not mark empty strings for translation.


Please make sure you use [http://www.gnu.org/software/gettext/manual/html_mono/gettext.html#SEC150 dgettext] for any pluralized strings.
See also [https://developer.gnome.org/glib/unstable/glib-I18N.html#Q-:CAPS how to disambiguate a string].
== Submit finished work ==


== Tools for translators ==
After you translated a file there are three possible means to submit it (the third is preferred as it allows to review the changes easily). These allow to discuss your work and gather relevant information at a dedicated place; they also require you to have an account, please see links below.
* emacs' po-mode (contained in the gettext distribution; the version in po-utils is old)
* kbabel (http://i18n.kde.org/tools/kbabel/)
* gtranslator (http://gtranslator.sourceforge.net/)
* poEdit (http://poedit.sourceforge.net/)


== A few important things to remember ==
* Simply send your file to Inkscape's translators mailing list.
* Some strings that can ambiguous or having several meanings according to different contexts may have a context prefix : "Context|Amibiguous string". In this case, simply translate "Ambiguous string", the "Context|" string is just a not to translate indication.
* After translating a fuzzy string (one that is marked with a ", fuzzy" comment), please remove its "fuzzy" tag -- otherwise this translation will be discarded by the build process, meaning that this string will show up untranslated. KBabel can do this automatically (see KBabel settings).
* Before publishing your work (after you have finished updating the PO file), please update the "PO-Revision-Date" and "Last-Translator" fields in the PO file header. KBabel can do this automatically.


== Review ==
* Upload your file via the bug tracker for the proper repository: [https://gitlab.com/inkscape/inbox/-/issues Inkscape interface and documentation], [https://gitlab.com/inkscape/inkscape-web-i18n/issues website].<br/>Open a new bug report titled ‘Translation to <your language>’ and attach the files you created or modified to it.
This is the start of a list of places to get translation reviews done.  So far:
  http://www.linux.it/tp/


== Locale Testing ==
* Create a merge request on GitLab ([https://gitlab.com/inkscape/inkscape/ Inkscape interface], [https://gitlab.com/inkscape/inkscape-docs/documentation/ documentation], [https://gitlab.com/inkscape/inkscape-web website]):
Before reporting that a locale doesn't work in Inkscape, you need to make sure that your system has that locale correctly set up.  To do this, you need to generally find a way to run "locale-gen". (Under Debian/Ubuntu this is via "dpkg-reconfigure locales".) If you set both the LANG and LANGUAGE variables and check a regular tool, you should see the correct language for both the libc error (first line) and the tool error (second line):
*# Visit the repository on GitLab, and click on 'Fork' to create your own, independent repository.
*# Make your changes to the code. There are two possibilities:
*#* Edit the files directly in your repository on the GitLab website via the provided web UI. ''(no prior knowledge required, but please make sure to create a new branch for your work, otherwise this may cause problems for you in the future.)''. Helpful instructions can be found here: https://gitlab.com/inkscape/inkscape/-/merge_requests/6670#note_2102133093.
*#* Download the code to you computer to work with it locally and re-upload it later. ''(some [[Working with Git|Git]] knowledge required)''
*#: Checkout the fork's code to you computer:
*#:: <code>git clone https://gitlab.com/<your_username>/<repository-name></code>
*#: Replace the previous file for your language with your new file in the directory. If there is no previous file, put your file into the right place. Tell the system it must take care of your added/changed file with:
*#:: <code>git add /path/to/your-file.po</code>
*#: Commit your changes to your own repository (put the correct information instead of the <placeholders>):
*#:: <code>git commit -m "Translated <file> for <language>, <xx>% complete</code>
*#:: <code>git push</code>
*# Visit your repository on the GitLab website, go to 'Merge requests' and make a new merge request, asking for your work to be reviewed and included in the correct branch, as well as also to forward port the changes to the master branch. Make sure to enable the boxes to 'allow edits by maintainers' and to 'squash commits'.


LANG=es_MX LANGUAGE=es_MX ls -z
Many thanks for your work!
ls: opci&oacute;n inv&aacute;lida -- z
Pruebe `ls --help' para m&aacute;s informaci&oacute;n.


If it reports the regular C messages, your locale has not been correctly configured, and you'll need to find the right way to run "locale-gen" for your distribution:
== Review ==


LANG=es_ES LANGUAGE=es_MX ls -z
This is the start of a list of places to get translation reviews done. So far:
ls: invalid option -- z
* http://www.linux.it/tp/
Try `ls --help' for more information.


== Programmers ==
[[Category:Translation]]
Please make sure you use [http://www.gnu.org/software/gettext/manual/html_mono/gettext.html#SEC150 dgettext] for any pluralized strings.

Latest revision as of 13:27, 12 September 2024

This page gathers useful information about translation.

Links and docs

PO translation files

Add a new translation file

If the PO file for your language does not exist yet, then you must create it as a copy of the translation template. This template is a file whose name ends with .pot. It contains the strings to translate without any translation. Create a copy and put it to the right place (just see how other languages are managed).

Tools for translators

You can edit PO files from any plain text editor, since they are simple text files. However, many useful tools have been developed to provide a simple experience translating PO files.

Recommended:

You might also try:

  • Emacs's po-mode (contained in the gettext distribution; the version in po-utils is old);
  • gedit — text editor for GNOME desktops, has a syntax highlight mode for PO file syntax;
  • Virtaal — cross-platform PO editor that is clean, simple to use yet powerful;
  • Gtranslator (GNOME).

And last but not least, gettext utils, which are installed on every Linux distribution. You can see a complete reference too from installed info pages by running the command:

info gettext

Update a translation file

If a translation file is already present for your language but the programmers have updated the template (.pot) since the translation was done, you need to sync the PO file with the template, especially for the new strings being added, but also for other info: position of the original string in the project, removing or marking obsolete strings, recognizing small string modifications…

Some software offers the ability to automatically sync the translation file with the template, e.g. with Poedit you can use the menu option ‘Catalog > Update from POT file…’.

GNU gettext also provides the command msgmerge. You can use it like this to update lt.po from inkscape.pot:

msgmerge -U lt.po inkscape.pot

File format

If you open a PO file with a text editor for the first time, you will find its syntax very simple. The PO format is a really simple format, which probably at least partly explains its success and widespread use. The format is basically a hash list consisting of msgid and msgstr pairs, with the msgid being the original English string and key, and the msgstr being the translated value of it. Below is an example of a message.

#: gedit/dialogs/gedit-plugin-program-location-dialog.c:78
#: gedit/dialogs/program-location-dialog.glade2.h:2
msgid "Set program location..."
msgstr "Ställ in programplats..."

In addition to the msgid and msgstr parts, a message usually also has lines starting with #: that tell what source files and what lines the string used as msgid was extracted from. These lines have no syntactic value. They are only there as a help for translators and developers to know where a message came from.

A message in a PO file can be in one of essentially three different states. The message can be translated, fuzzy, or untranslated. A message counts as translated as soon as the msgstr part of it is non-empty. In a similar manner, an untranslated message is one where the msgstr is empty. The fuzzy state is special and essentially means that there is a translation in the msgstr part, but that this translation is most likely not entirely correct, and that it thus needs manual attention by a translator. A message can become fuzzy in one of two ways:

  • The original string that the msgid represents was changed in the source code. A typo in the string may have been fixed or the string altered in some other way. The translator needs to check that the msgstr is still valid and make changes if necessary.
  • A new string has been added to the source, and the string is similar (but not identical) to the msgid of an already existing, translated message. Then the msgstr of that message will be automatically reused for the new message, but the new message will also at the same time be marked fuzzy so that the translator knows there is some difference that he or she needs to adapt the translation to match.

A few important things to remember

  • Some strings that can be ambiguous or having several meanings according to different contexts may have a context prefix: ‘Context|Ambiguous string’. In this case, give the translation for ‘Ambiguous string’ only; the ‘Context|’ part is just a not to translate indication.
  • After translating a fuzzy string (one that is marked with a ", fuzzy" comment), please remove its fuzzy tag — otherwise this translation will be discarded by the build process, meaning that this string will show up untranslated.
  • Before publishing your work (after you have finished updating the PO file), please update the "PO-Revision-Date" and "Last-Translator" fields in the PO file header.

If you use a translation software, it may deal with the last two points for you automatically (check the settings).

Verification

Before submitting your file to the project, you should make sure it is valid.

  • Make sure the file is encoded in UTF-8.
  • Make sure it is a valid PO file and obtain some statistics about it: simply run msgfmt --statistics -cv translation_file.po from a command window.
  • Make sure it is correctly formatted: run check-markup translation_file.po from a command window and verify it doesn't output any error message. The ‘check-markup’ Perl script can be found in the /po directory of Inkscape trunk.

If your translation software can compile PO files to .mo, it should detect any errors when you save your translations so you don't need to do any further verifications.

Programmers

There is always one special message in each valid PO file: the PO file header. It is encoded with the msgid for the empty string ("") as the key, and the actual header values are in the msgstr part. This unfortunately means that if you mark an empty string for translation, you will get the entire PO file header back as the ‘translation’. In almost all cases this is probably not what you want. Hence, do not mark empty strings for translation.

Please make sure you use dgettext for any pluralized strings.

See also how to disambiguate a string.

Submit finished work

After you translated a file there are three possible means to submit it (the third is preferred as it allows to review the changes easily). These allow to discuss your work and gather relevant information at a dedicated place; they also require you to have an account, please see links below.

  • Simply send your file to Inkscape's translators mailing list.
  • Upload your file via the bug tracker for the proper repository: Inkscape interface and documentation, website.
    Open a new bug report titled ‘Translation to <your language>’ and attach the files you created or modified to it.
  • Create a merge request on GitLab (Inkscape interface, documentation, website):
    1. Visit the repository on GitLab, and click on 'Fork' to create your own, independent repository.
    2. Make your changes to the code. There are two possibilities:
      • Edit the files directly in your repository on the GitLab website via the provided web UI. (no prior knowledge required, but please make sure to create a new branch for your work, otherwise this may cause problems for you in the future.). Helpful instructions can be found here: https://gitlab.com/inkscape/inkscape/-/merge_requests/6670#note_2102133093.
      • Download the code to you computer to work with it locally and re-upload it later. (some Git knowledge required)
      Checkout the fork's code to you computer:
      git clone https://gitlab.com/<your_username>/<repository-name>
      Replace the previous file for your language with your new file in the directory. If there is no previous file, put your file into the right place. Tell the system it must take care of your added/changed file with:
      git add /path/to/your-file.po
      Commit your changes to your own repository (put the correct information instead of the <placeholders>):
      git commit -m "Translated <file> for <language>, <xx>% complete
      git push
    3. Visit your repository on the GitLab website, go to 'Merge requests' and make a new merge request, asking for your work to be reviewed and included in the correct branch, as well as also to forward port the changes to the master branch. Make sure to enable the boxes to 'allow edits by maintainers' and to 'squash commits'.

Many thanks for your work!

Review

This is the start of a list of places to get translation reviews done. So far: