Difference between revisions of "Documentation Translation"

From GnuCash
Jump to: navigation, search
m (replace underline in wiki link)
m (Translating the GnuCash Guide and Manual: -> Manual and Guide)
 
(17 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
[[Category:Translation]]
 
[[Category:Translation]]
[[Category:Documentation Developmen]]
+
[[Category:Documentation Development]]
Purpose of this page is to help you to translate [parts of] the official documentation into your language to make it available
+
Purpose of this page is to assist you to translate [parts of] the official documentation into your language to make it available
 
* over the <tt>Help</tt> menu of the program,
 
* over the <tt>Help</tt> menu of the program,
 
* for download in several formats as
 
* for download in several formats as
**[{{WebURL}}/docs.phtml released version] or
+
**[{{URL:www}}docs.phtml released version] or
**[{{BuildURL}}/docs/ nightly snapshot].
+
**[{{URL:Build}}docs/ nightly snapshot].
  
 
If you are interested in improving the documentation, you should also read [[Documentation Improvement]].
 
If you are interested in improving the documentation, you should also read [[Documentation Improvement]].
Line 13: Line 13:
 
:project maintainers: [[Language Administration]].
 
:project maintainers: [[Language Administration]].
  
== Translating the GnuCash Guide and Help==
+
;Note: The instructions below have been adapted for the documentation related to GnuCash 5.0 or more recent. If you are looking or instructions to improve older documentation releases, please refer to [https://wiki.gnucash.org/wiki/index.php?title=Documentation_Translation&oldid=20988 an older version of this page].
 +
 
 +
== Translating the GnuCash Manual and Guide==
 
This section describes the actions needed to translate the manuals. There are currently 2 parts:
 
This section describes the actions needed to translate the manuals. There are currently 2 parts:
 +
* '''Manual''': This is shown by the context sensitive help system and describing the elements of the dialogs.
 
* ''Tutorial and Concept '''Guide''''': This is an introduction in the basic principles of double entry accounting and their application in GnuCash. This text is really useful for new users.  
 
* ''Tutorial and Concept '''Guide''''': This is an introduction in the basic principles of double entry accounting and their application in GnuCash. This text is really useful for new users.  
* '''Manual, ''' old name: ''Help'': This is the context sensitive help system. The renaming is in progress. The sources already use <tt>manual</tt>, but the installed document is still <tt>gnucash-help</tt>.
 
  
If you are interested in translating these documents, please decide whether you want ''only'' to translate the existing text or whether you want also to improve and cross-check the text with the actual status in the program in your language. It is less effort only to translate the text, but you also run into the risk of doing unnecessary work if you translate explanations which are no longer correct. It might be more effort to create a new text in your language, using the English text only as an inspiration, but it will surely lead to more useable and more helpful documentation. We, the programmers, encourage you to do the latter and create a new text in your language. As you are the one doing the work, the decision is up to you.
+
If you are interested in translating these documents, please decide whether you want ''only'' to translate the existing text or whether you want also to improve and cross-check the text with the actual status in the program in your language. It is less effort only to translate the text, but you also run into the risk of doing unnecessary work if you translate explanations which are no longer correct. It might be more effort to create a new text in your language, using the English text only as an inspiration, but it will surely lead to more usable and more helpful documentation. We, the programmers, encourage you to do the latter and create a new text in your language. As you are the one doing the work, the decision is up to you.
  
 
Both documents consist of  
 
Both documents consist of  
Line 32: Line 34:
 
Please use a ''unified terminology'': The translator of the program messages should have created [[#The glossary file]] for the translations of the key wordings in the program. Please make sure to use the same terms in the documents, too.
 
Please use a ''unified terminology'': The translator of the program messages should have created [[#The glossary file]] for the translations of the key wordings in the program. Please make sure to use the same terms in the documents, too.
  
You can check the [{{BuildURL}}/docs/ nightly builds] - in particular after your updates were committed.
+
You can check the [{{URL:Build}}docs/ nightly builds] - in particular after your updates were committed.
  
 
=== Prerequisites ===
 
=== Prerequisites ===
 
==== Linux ====
 
==== Linux ====
In addition to the software for running autogen.sh, the following additional software is needed for the development on Linux. From the [{{URL:GH}}Gnucash/gnucash-docs/blob/maint/README gnucash-docs/README] file as of 2019-02-19:
+
In addition to
 +
*Cmake and one of
 +
** Make or
 +
** Ninja
 +
the following additional software is needed for the development on Linux. From the [{{URL:GH}}Gnucash/gnucash-docs/blob/stable/README gnucash-docs/README] file as of 2019-02-19:
  
 
:* libxml2
 
:* libxml2
Line 42: Line 48:
 
::          which depends on libxslt]
 
::          which depends on libxslt]
 
:* docbook-xsl
 
:* docbook-xsl
:* rarian or
+
;at runtime: yelp (for viewing under linux)
:: scrollkeeper >=0.3.4 (its ancestor)
 
:* yelp (for viewing)
 
  
:Optional:
+
;Optional:
 
:* gnome-doc-utils (contains <tt>xml2po</tt> for the use of po editors like in the it translation)
 
:* gnome-doc-utils (contains <tt>xml2po</tt> for the use of po editors like in the it translation)
  
:Additional Requirements for Generating Mobipocket:
+
:;by target format:
:* Calibre (https://www.calibre-ebook.com/)
+
::; Mobipocket:
 +
:::* Calibre (https://www.calibre-ebook.com/)
  
:Additional Requirements for Generating chm:
+
::;chm (old fashioned Windows Help):
:* Mingw (http://www.mingw.org)
+
:::* Mingw (http://www.mingw.org)
:* Html Help Workshop ({{URL:MS}}en-us/download/details.aspx?id=21138 for Win XP - 8)
+
:::* Html Help Workshop ({{URL:MS}}en-us/download/details.aspx?id=21138 for Win XP - 8)
  
:Additional Requirements for Generating PDF:
+
::;PDF:
:* Apache fop  >= 0.95
+
:::* Apache fop  >= 0.95
:For the Japanese PDF, Japanese fonts are included. If you want to use other Japanese fonts you can use the --with-japanese-fonts-dir, --with-japanese-mincho-ttf, and --with-japanese-gothic-ttf configure options to select them. fop's TTFReader can't, as of version 1.1 anyway, handle OpenType fonts.
+
:::;For non-latin scripts:
 +
:::* Fonts. For the Japanese PDF, Japanese fonts are included. If you want to use other Japanese fonts you can use the --with-japanese-fonts-dir, --with-japanese-mincho-ttf, and --with-japanese-gothic-ttf configure options to select them. fop's TTFReader can't, as of version 1.1 anyway, handle OpenType fonts.
  
'''Note for wiki editors:''' Keep above section in sync with [{{URL:GH}}Gnucash/gnucash-docs/blob/maint/README gnucash-docs/README]
+
'''Note for wiki editors:''' Keep above section in sync with [{{URL:GH}}Gnucash/gnucash-docs/blob/stable/README gnucash-docs/README]
  
 
==== Other Operating Systems ====
 
==== Other Operating Systems ====
Line 107: Line 113:
  
 
=== The Procedure ===
 
=== The Procedure ===
;Note: The procedure explains what needs to be done to add a new translation to the guide. If you want to add a new translation for the help manual, make the following replacements:
+
;Note: The procedure explains what needs to be done to add a new translation to the guide. If you want to add a new translation for the manual, make the following replacements:
{| class="wikitable"
+
{| class="wikitable" style="text-align: center;"
 +
! scope="col"|Place
 +
! colspan="2"|Component
 
|-
 
|-
|guide||manual||source directory name
+
! scope="row"|source directory name
 +
|guide
 +
|manual
 
|-
 
|-
|gnucash-guide||gnucash-help||document name
+
! scope="row"|document name
 +
|gnucash-guide
 +
|gnucash-manual
 
|}
 
|}
 
First, you have to download the most recent version of the gnucash-docs package. This is done as follows:
 
First, you have to download the most recent version of the gnucash-docs package. This is done as follows:
 
 
# Checkout the documentation in a directory ''gnucash-docs'':
 
# Checkout the documentation in a directory ''gnucash-docs'':
#: <syntaxhighlight lang="sh">git clone ${URL} -b maint gnucash-docs</syntaxhighlight> with ${URL}={{URL:GH}}Gnucash/gnucash-docs
+
#: <syntaxhighlight lang="sh">git clone ${URL} -b stable gnucash-docs</syntaxhighlight> with ${URL}={{URL:GH}}Gnucash/gnucash-docs
# Create your working branch. If you plan to use pull requests, you should use unique names like ''guide-LL-chapter-x-part-n'' instead of working-branch.
+
# Create your working branch. If you plan to use pull requests, you should use unique names like ''LL-guide-chapter-x-part-n'' instead of working-branch.
 
#: <syntaxhighlight lang="sh">git checkout -b working-branch</syntaxhighlight>
 
#: <syntaxhighlight lang="sh">git checkout -b working-branch</syntaxhighlight>
# Create a new directory (if it doesn't already exist) as guide/<locale> where <locale> is of the form <language>[_<region>] e.g. es, en_GB, or pt_PT. See [[#Naming Conventions]]: <syntaxhighlight lang="sh">
+
#;If this is the first GnuCash document in your language:
mkdir -p ${COMPONENT}/${LOCALE}
+
## Create a new directory (if it doesn't already exist) as <locale> where <locale> is of the form <language>[_<region>] e.g. es, en_GB, or pt_BR. See [[#Naming Conventions]] and [[Locale_Settings#IETF_language_tags]]: <syntaxhighlight lang="sh">
</syntaxhighlight>
+
LOCALE=LA # Replace Latin by your languages code
#:See [[Locale_Settings#IETF_language_tags]] for details.
+
mkdir -p ${LOCALE}
#:If your translation is the first for your language do not add a region code. So also other regions benefit from your translation.
+
</syntaxhighlight> If your translation is the first for your language ''do not append a region code''. So also other regions benefit from your translation.
#:And copy the files from guide/C into this directory: <syntaxhighlight lang="sh">cp -r guide/C guide/LL</syntaxhighlight>
+
## Copy C/CMakeLists.txt into your ${LOCALE}/ directory and inside ${LOCALE}/CMakeLists.txt
#:;Not in latin letters written languages: They need additional files to process printing to pdf. See <tt>ja</tt> or <tt>ru</tt> as examples.
+
### adjust the locale string in the first line of this file to match your directory name;
# Add an entry for your directory in [guide/]'''CMakeLists.txt'''. The format is <syntaxhighlight lang="cmake">
+
### adjust the following two lines (the ones starting with add_directory). Prepend both with a ''#'' sign. That will disable these documents in your language for now. We'll re-enable them as we add the proper document directories later on.
add_directory(<language>)
+
## In '''CMakeLists.txt''' in the ''toplevel'' of your source directory add an ''add_subdirectory'' entry for your language. The format is <syntaxhighlight lang="cmake">
</syntaxhighlight>. There are other examples in those files you can follow. Please keep the language list sorted alphabetically.
+
add_subdirectory(${LOCALE})</syntaxhighlight>
# Notify git about the new directory and files. "*" is quoted by "\".
+
##;Attention: Replace <q>${LOCALE}</q> by its content here.
#: <syntaxhighlight lang="sh>git add guide/$LL/\*.\*</syntaxhighlight> or <syntaxhighlight lang="sh>git add manual/$LL/\*.\*</syntaxhighlight>
+
##:There are other examples in that file you can follow.
 +
##:Please keep the language list sorted alphabetically.
 +
##Create a localized dtd
 +
##: It should primary contain the localization of the program's GUI elements like menu entries and is used in many places.
 +
###<syntaxhighlight lang="sh">cp dokbook/gnc-gui-C.dtd dokbook/gnc-gui-${LOCALE}.dtd</syntaxhighlight>
 +
###Localize its content. Example: The first enry is [{{URL:GH}}Gnucash/gnucash-docs/blob/e53a0bfd60d87d0150a8dfaf4f1aad3b67fa5ada/docbook/gnc-gui-C.dtd#L25-L26 docbook/gnc-gui-C.dtd#L25-L26] <syntaxhighlight lang="xml">
 +
<!-- File-Menu -->
 +
<!ENTITY % gm.file "<guimenu><accel>F</accel>ile</guimenu>">
 +
</syntaxhighlight> Replace Docbooks <code><accel>F</accel></code> by Gnomes gettext convention <code>_F</code> and search in the '''program''''s po file of your language for the string <code>"_File"</code> i.e. [{{URL:GH}}Gnucash/gnucash/blob/16c9957cac7b2ca2fe4b2b4a25c92878fcd4067b/po/zh_CN.po#L27145-L27147 zh_CN.po#L27145-L27147] <syntaxhighlight lang="po">
 +
#: gnucash/ui/gnc-main-window.ui:8
 +
msgid "_File"
 +
msgstr "文件(_F)"
 +
</syntaxhighlight> Convert the msgstring in the other direction and store <code>文件(<accel>F</accel>)</code> as  value of gm.file in gnc-gui-zh.dtd. You can fasten that by using <syntaxhighlight lang="console">$ msggrep --msgid -e '_File' po/zh_CN.po
 +
# GnuCash PO file, for Simplified Chinese.
 +
[–]
 +
 
 +
#: gnucash/gtkbuilder/dialog-doclink.glade:276
 +
msgid "Linked _File"
 +
msgstr "本地文件(_F)"
 +
 
 +
#: gnucash/ui/gnc-main-window.ui:8
 +
msgid "_File"
 +
msgstr "文件(_F)"
 +
 
 +
#: gnucash/ui/gnc-plugin-basic-commands.ui:6
 +
msgid "New _File"
 +
msgstr "新建(_F)"
 +
 
 +
</syntaxhighlight> in you programs top source directory. Continue with the next entry …
 +
##:Perhaps someone would provide a script?
 +
## Copy the guide directory from C (English language) into this directory: <syntaxhighlight lang="sh">cp -r C/guide ${LOCALE}/guide</syntaxhighlight>
 +
##:;For languages that don't use latin characters: They need additional files to process printing to pdf. See <tt>ja</tt>, <tt>ru</tt>, or <tt>zh</tt> as examples.
 +
## Tell your documents to use your localized dtd: <syntaxhighlight lang="sh>
 +
cd ${LOCALE}/guide
 +
for i in *.dokbook; do sed -i "s/gnc-gui-C.dtd/gnc-gui-${LOCALE}.dtd/" $i; done
 +
for i in *.xml; do sed -i "s/gnc-gui-C.dtd/gnc-gui-${LOCALE}.dtd/" $i; done
 +
cd ../..</syntaxhighlight>
 +
## Notify git about the new directory and files. "*" is quoted by "\".
 +
##: <syntaxhighlight lang="sh>git add ${LOCALE}/CMakeLists.txt ${LOCALE}/guide/\*.\*</syntaxhighlight> or <syntaxhighlight lang="sh>git add ${LOCALE}/CMakeLists.txt ${LOCALE}/manual/\*.\*</syntaxhighlight>
 
# Now the real work:  
 
# Now the real work:  
## Edit '''all the xml files''' (see [[#DocBook xml editors]] below for suitable editor programs) and translate them into your language.
+
## Edit '''index.docbook and all the xml files''' (see [[#DocBook xml editors]] below for suitable editor programs) and translate them into your language.
 
##* In the event the english documents get updated, it might be useful to have a comment in the header of each chapter in  the form:
 
##* In the event the english documents get updated, it might be useful to have a comment in the header of each chapter in  the form:
##: <syntaxhighlight lang="xml"><!-- Translation based on maint/master commit 1234567 2014-01-01 10:00 UTC --></syntaxhighlight>
+
##: <syntaxhighlight lang="xml"><!-- Translation based on {stable|future} branch, commit 1234567 2023-01-01 10:00 UTC --></syntaxhighlight>
##: Then you can later view a diff between the current and that version of the english file in one window to locate the changes and adjust the translation in another window. Some translators like to do also the translation in a graphical diff program like KDiff3 between english and their language because the <code><sectN id></code>s will synchronize the text.
+
##: Then you can later view a diff between the current and that version of the english file in one window to locate the changes and adjust the translation in another window. Some translators like to do also the translation in a graphical diff program like KDiff3 between english and their language because the <code><sectN id></code>s will synchronize the text.
##* Use the same terminoloy as in [[#The_glossary_file]]. If you did not [[#Get_the_source_from_Git]], you can simply download your languages .po file from the [{{URL:GH}}Gnucash/gnucash/tree/maint/po/glossary glossary directory at GitHub].
+
##;Use consistent terminology:
 +
##:;Program's Glossary: If you did not [[Translation#Get_the_source_from_Git]], you can simply download your languages .po file from
 +
##::* after selection in [{{URL:wl}}glossary/ weblate gnucash glossary] from the <tt>Files</tt> menu or
 +
##::* the [{{URL:GH}}Gnucash/gnucash/tree/stable/po/glossary glossary directory at GitHub].
 +
##::Verify its completeness and ''use its content in your translation''. If it is not complete, update it according [[Translation#The_glossary_file]].
 +
##:;Guide's Glossary: Verify that you have a recent version of [{{URL:GH}}Gnucash/gnucash-docs/blob/stable/C/guide/gnc-glossary.xml C/guide/gnc-glossary.xml] in your languages subtree and ''translate it''—also for your later use.
 +
##;Use existing entities: See [[Documentation_Improvement#Conventions]]
 +
##:;Familiarize yourself with the global entities: They are defined in [{{URL:GH}}Gnucash/gnucash-docs/blob/stable/docbook/gnc-docbookx.dtd docbook/gnc-docbookx.dtd]
 +
##:;Localize the GUI entities: run Gnucash in your language and adjust the GUI elements in a copy from [{{URL:GH}}Gnucash/gnucash-docs/blob/stable/docbook/gnc-gui-C.dtd docbook/gnc-gui-C.dtd] into docbook/gnc-gui-${LOCALE}.dtd.
 
## <s>There are some general headers, which do not appear in the xml-files in your locale directory. But they can be translated by adding ''a section in '''xsl/l10n.xml'''''. Obey the comment at the beginning. If you use non-ASCII characters, you should run <code>recode -d <input_encoding>..h0 l10n.xml</code>, where input_encoding might be u8 for UTF8, to get them right encoded.</s> Obsolete?
 
## <s>There are some general headers, which do not appear in the xml-files in your locale directory. But they can be translated by adding ''a section in '''xsl/l10n.xml'''''. Obey the comment at the beginning. If you use non-ASCII characters, you should run <code>recode -d <input_encoding>..h0 l10n.xml</code>, where input_encoding might be u8 for UTF8, to get them right encoded.</s> Obsolete?
## In addition to the text, you need to ''recreate the image files in '''guide/C/figures''''' so that they are appropriate to your language. For details (size, style,...) see [[Documentation_Update_Instructions#Screenshots And Other Images]].
+
## In addition to the text, you need to ''recreate the image files in '''C/guide/figures''''' so that they are appropriate to your language. For details (size, style,...) see [[Documentation_Update_Instructions#Screenshots And Other Images]].
 
### Most of them are '''screenshots''' of a gnucash session - save them as png files because this will use a lossless compression. In theory some of the files in gnucash/doc/examples could be a starting point therefor, but they are currently - 2010-09-17 - broken.
 
### Most of them are '''screenshots''' of a gnucash session - save them as png files because this will use a lossless compression. In theory some of the files in gnucash/doc/examples could be a starting point therefor, but they are currently - 2010-09-17 - broken.
 
### A few figures are in '''scalable vector graphic''' (svg) format. Here you can edit the files e.g. in ''Libre/OpenOffice'' and translate the strings and adjust the size.
 
### A few figures are in '''scalable vector graphic''' (svg) format. Here you can edit the files e.g. in ''Libre/OpenOffice'' and translate the strings and adjust the size.
 
## Watch out: The documentation itself is ''probably outdated in many places'', as it has been written for the 1.8.0 version of gnucash. You can watch the current progress in [[Concept_Guide#Ongoing_work]]. If you encounter any description that is wrong for the current version of gnucash, do not hesitate to ignore the english original text and instead describe the situation of the current version of gnucash in your translation. It would be even better if you have the time to change the english original text as well, or at least ''file a bug against it'', but even if you can't do that, feel free to describe the actual state of gnucash in your translation and simply ignore the original english text.
 
## Watch out: The documentation itself is ''probably outdated in many places'', as it has been written for the 1.8.0 version of gnucash. You can watch the current progress in [[Concept_Guide#Ongoing_work]]. If you encounter any description that is wrong for the current version of gnucash, do not hesitate to ignore the english original text and instead describe the situation of the current version of gnucash in your translation. It would be even better if you have the time to change the english original text as well, or at least ''file a bug against it'', but even if you can't do that, feel free to describe the actual state of gnucash in your translation and simply ignore the original english text.
 
##: If you file a patch against the english text, you can also file a patch, which adds your name and email address to AUTHORS, so you will become famous. ;-) Ask to apply this latter patch also against gnucash/DOCUMENTERS because both files should have the same content. More details about editing the english text can be found in the [[Documentation Update Instructions]].  
 
##: If you file a patch against the english text, you can also file a patch, which adds your name and email address to AUTHORS, so you will become famous. ;-) Ask to apply this latter patch also against gnucash/DOCUMENTERS because both files should have the same content. More details about editing the english text can be found in the [[Documentation Update Instructions]].  
# Test your xml files for syntax errors by running ''xmllint'' on the '''main file''' ''gnucash-{guide|help}.xml'', e.g.:
+
# Test your xml files for syntax errors by running ''xmllint'' on the '''main file''' ''index.docbook'', e.g.:
 
#: <Syntaxhighlight lang="sh">
 
#: <Syntaxhighlight lang="sh">
 
cd ${gnucash-docs-dir} # adjust to navigate to your local gnucash-docs source directory
 
cd ${gnucash-docs-dir} # adjust to navigate to your local gnucash-docs source directory
xmllint --postvalid --xinclude --noout --path docbook guide/>LL>/gnucash-guide.xml # replace <LL> with your language code
+
xmllint --postvalid --xinclude --noout --path docbook ${LOCALE}/guide/index.docbook
 
</Syntaxhighlight>
 
</Syntaxhighlight>
 
#: The program ''xmllint'' is part of the package '''libxml'''.
 
#: The program ''xmllint'' is part of the package '''libxml'''.
 
#: '''Tip:''' Some ''xml aware editors'' have a menu entry like ''validate'' to run this test though they will likely be missing the path to the docbook directory that holds our custom DTD.  
 
#: '''Tip:''' Some ''xml aware editors'' have a menu entry like ''validate'' to run this test though they will likely be missing the path to the docbook directory that holds our custom DTD.  
# Optional: test your work with yelp - there are build system methods to support you:
+
# Other recommended testing and validation options include opening your files in yelp and proofreading in html or pdf format. These extra options require you to generate your translated documentation in the proper formats. How to do so is described in more detail in [[Documentation Update Instructions]]. Please refer to that page for further instructions.
## Using a terminal, go to your gnucash-docs directory <SyntaxHighlight lang="sh">
 
cd /path/to/gnucash-docs # replace the example path with your real path
 
</SyntaxHighlight>
 
## Make a build directory next to your source directory and go into it <SyntaxHighlight lang="sh">
 
mkdir ../gnucash-docs-build
 
cd ../gnucash-docs-build
 
</SyntaxHighlight>
 
## Configure the build system<SyntaxHighlight lang="sh">
 
cmake -D CMAKE_INSTALL_PREFIX=../gnucash-docs-install ../gnucash-docs
 
</SyntaxHighlight>
 
##: These commands will set up a directory structure as follows:<SyntaxHighlight lang="sh">
 
path/to/
 
  gnucash-docs/          # directory with gnucash-docs sources
 
  gnucash-docs-build/    # directory to generate gnucash-docs in various formats
 
  gnucash-docs-install/  # directory to install final result (not needed for development, just for completeness)
 
</SyntaxHighlight>
 
##: There are plenty of other options you can pass to either configure or cmake, but that's outside of the scope of this wiki page.
 
#: The steps above only have to be run once (though running it more than once is safe). What follows can be repeated as often as needed while working on the docs.
 
## To check your work while editing you can run <SyntaxHighlight lang="sh">
 
make check
 
</SyntaxHighlight> in the build directory. That will However check ''all'' documentation, not just the one you're working on.
 
## If you want to check only your work you can add a ''target'' to the command to refers to your work specifically. In this example we will check work on the German version of the guide: <SyntaxHighlight lang="sh">
 
make de-gnucash-guide-check
 
</SyntaxHighlight>
 
##:Note the command always is entered in the top-level of the build directory.
 
##: This will run the  <syntaxhighlight lang="sh" inline>
 
xmllint</syntaxhighlight> command above over the full directory structure.
 
## As an aside you can generate the documentation in other formats, like pdf or html by replacing ''check'' in the command above with ''pdf'' or ''html'' respectively: <SyntaxHighlight lang="sh">
 
make de-gnucash-guide-pdf
 
</SyntaxHighlight>
 
## To see your work in yelp use the following command <SyntaxHighlight lang="sh">
 
# In the command below, replace
 
# <language> with the language of the doc you want to view, for example C (for English), de (for German),...
 
# /path/to/gnucash-docs-build with the real path to the gnucash-docs build directory you created earlier
 
# <docname> with the document you wish to view, either gnucash-help or gnucash-guide
 
LANG=<language> XDG_DATA_DIRS=/path/to/gnucash-docs-build/share:${XDG_DATA_DIRS}:/usr/local/share:/usr/share yelp gnome-help:<docname>
 
# Example:
 
LANG=pt XDG_DATA_DIRS=/path/to/gnucash-docs-build/share:${XDG_DATA_DIRS}:/usr/local/share:/usr/share yelp gnome-help:gnucash-guide
 
</SyntaxHighlight>This uses yelp's built-in mechanism to select the proper language.
 
## Alternatively you can open the generated document directly via: <SyntaxHighlight lang="sh">
 
yelp /path/to/gnucash-docs-build/share/gnome/help/<docname>/<language>/<docname>.xml
 
</SyntaxHighlight>You need to make the same replacements as in the other form.
 
 
## Repeat these steps until you're satisfied with the result.
 
## Repeat these steps until you're satisfied with the result.
 
# Update the branches of your local repo often: <SyntaxHighlight lang="sh">
 
# Update the branches of your local repo often: <SyntaxHighlight lang="sh">
git checkout maint              # switch to maint
+
git checkout stable              # switch to the stable branch
 
git pull --rebase                # update it
 
git pull --rebase                # update it
git rebase maint working-branch # update working-branch
+
git rebase stable working-branch # update working-branch
 
git checkout working-branch      # switch back to working-branch
 
git checkout working-branch      # switch back to working-branch
 
</SyntaxHighlight>
 
</SyntaxHighlight>
 
# Follow [[#Submitting your work direct to GnuCash]].
 
# Follow [[#Submitting your work direct to GnuCash]].
  
'''Committers:''' If it builds fine, add the directory changes from 2. also to <tt>gnucash/maint/packaging/win32/install-impl.sh</tt> and merge the change to master, if required.
+
'''Committers:''' If it builds fine, add the directory changes from 2. also to <tt>gnucash/stable/packaging/win32/install-impl.sh</tt> and merge the change to future, if it exists and they are required there.
  
 
=== DocBook xml editors ===
 
=== DocBook xml editors ===
 
 
For editing these DocBook xml files, various editors can be used: {{URL:wp}}DocBook might contain pointers to some, or also https://www.tldp.org/LDP/LDP-Author-Guide/html/tools-edit.html.
 
For editing these DocBook xml files, various editors can be used: {{URL:wp}}DocBook might contain pointers to some, or also https://www.tldp.org/LDP/LDP-Author-Guide/html/tools-edit.html.
 
:Some developers use [[Eclipse]].
 
:Some developers use [[Eclipse]].
Line 214: Line 228:
  
 
=== Using po editors ===
 
=== Using po editors ===
 
+
Some translators are more familiar with using po file editors like poedit, Kbabel, Gtranslator etc. For those people, it is possible to convert the content of the documents (the DocBook XML files) into po files, translate the messages in the po file, and convert the result back into xml. This section describes how to use this approach for the GnuCash documentation.
Some translators are more familiar with using po file editors like poedit, Kbabel, Gtranslator etc. For those people, it is possible to convert the content of the help documents (the DocBook XML files) into po files, translate the messages in the po file, and convert the result back into xml. This section describes how to use this approach for the gnucash help documents.
 
  
 
;The downside of this approach: It will be much harder for the documenters to fix e.g. broken links in times where you are inactive.
 
;The downside of this approach: It will be much harder for the documenters to fix e.g. broken links in times where you are inactive.
Line 221: Line 234:
 
In order to use po files you have first to convert xml files to po files, translate them and then convert back to xml.
 
In order to use po files you have first to convert xml files to po files, translate them and then convert back to xml.
  
First you have to install a fresh version of gnome-doc-utils. For example in a Fedora 13 system: <syntaxhighlight lang="sh">
+
:;Prerequisite: First you have to install a fresh version of '''gnome-doc-utils'''. For example in a Fedora 13 system: <syntaxhighlight lang="sh">
 
yum install gnome-doc-utils
 
yum install gnome-doc-utils
</syntaxhighlight>
+
</syntaxhighlight> Other distributions might have split it as a separate <tt>[python-]xml2po</tt> package.
  
#Do the conversion with the following commands (xx is your language code, example: el for Greek): <syntaxhighlight lang="sh">
+
#Do the conversion with the following commands (${LL} is your language code, example: el for Greek): <syntaxhighlight lang="sh">
xml2po -o helpfile.xml.pot helpfile.xm
+
#Append your language code
mv helpfile.xml.pot helpfile.xml.xx.po
+
LL=
 +
# and the desired component {manual|guide}
 +
COMPONENT=
 +
# Create pot
 +
## cd to get short references:
 +
cd C/${COMPONENT}
 +
## (it seems to reverse the order)
 +
## if already translated xml files exist, specify them with -r
 +
xml2po -k -o ../../${COMPONENT}.pot *.xml index.docbook
 +
cd ../..
 +
# Create target directories
 +
mkdir -p ${LL}/${COMPONENT}/figures
 +
cp C/${COMPONENT}/CMakeLists.txt ${LL}/${COMPONENT}/
 +
cd ${LL}/${COMPONENT}
 +
# Create po
 +
## If on behalf of others, append --no-translator
 +
msginit -l$LL -i../../${COMPONENT}.pot
 +
cd ../..
 
</syntaxhighlight>
 
</syntaxhighlight>
#Translate helpfile.xml.xx.po using your favorite po editor.
+
#Translate ${LL}.po using your favorite po editor.
 
#Convert back to xml: <syntaxhighlight lang="sh">
 
#Convert back to xml: <syntaxhighlight lang="sh">
xml2po -e -p helpfile.xml.xx.po -o xx_helpfile.xml helpfile.xml
+
cd C/${COMPONENT}
 +
  xml2po -p ../../${LL}/${COMPONENT}/${LL}.po -o ../../${LL}/${COMPONENT}/index.docbook index.docbook
 +
for i in *.xml; do
 +
  xml2po -p ../../${LL}/${COMPONENT}/${LL}.po -o ../../${LL}/${COMPONENT}/$i $i;
 +
done
 +
cd ../..//${LL}/${COMPONENT}
 +
echo Do not add ${COMPONENT}.pot into git!
 
</syntaxhighlight>
 
</syntaxhighlight>
 
#Test your translated xml file as mention above: <syntaxhighlight lang="sh">
 
#Test your translated xml file as mention above: <syntaxhighlight lang="sh">
xmllint --valid --noout xx.helpfile.xml
+
xmllint --valid --noout /${LL}/${COMPONENT}/index.docbook
</syntaxhighlight> Remove xx from xx_helpfile.xml and you are ready to commit it in your language help directory
+
</syntaxhighlight> Now you still have to create the images.
  
 
=== GnuCash Maintainer Tasks ===
 
=== GnuCash Maintainer Tasks ===

Latest revision as of 16:12, 13 May 2024

Purpose of this page is to assist you to translate [parts of] the official documentation into your language to make it available

If you are interested in improving the documentation, you should also read Documentation Improvement.

There are other related pages for

programmers: I18N and
project maintainers: Language Administration.
Note
The instructions below have been adapted for the documentation related to GnuCash 5.0 or more recent. If you are looking or instructions to improve older documentation releases, please refer to an older version of this page.

Translating the GnuCash Manual and Guide

This section describes the actions needed to translate the manuals. There are currently 2 parts:

  • Manual: This is shown by the context sensitive help system and describing the elements of the dialogs.
  • Tutorial and Concept Guide: This is an introduction in the basic principles of double entry accounting and their application in GnuCash. This text is really useful for new users.

If you are interested in translating these documents, please decide whether you want only to translate the existing text or whether you want also to improve and cross-check the text with the actual status in the program in your language. It is less effort only to translate the text, but you also run into the risk of doing unnecessary work if you translate explanations which are no longer correct. It might be more effort to create a new text in your language, using the English text only as an inspiration, but it will surely lead to more usable and more helpful documentation. We, the programmers, encourage you to do the latter and create a new text in your language. As you are the one doing the work, the decision is up to you.

Both documents consist of

  • text files in an XML format called DocBook, where the complete document is split into a collection of xml files by chapter, and
  • images:
    • In the few scalable vector graphics (SVG) you can replace the text in you localized file.
    • But most are screenshots stored as Portable Network Graphics (png) files in the subdirectory figures/. The xml files will contain links to the png files where they should appear in the text.
See also
Documentation Update Instructions#Screenshots And Other Images

At the beginning you might wish to concentrate on the text. If desired, you could link the english pictures from C/figures.

You can find an introduction to DocBook in Creating DocBook Documents.

Please use a unified terminology: The translator of the program messages should have created #The glossary file for the translations of the key wordings in the program. Please make sure to use the same terms in the documents, too.

You can check the nightly builds - in particular after your updates were committed.

Prerequisites

Linux

In addition to

  • Cmake and one of
    • Make or
    • Ninja

the following additional software is needed for the development on Linux. From the gnucash-docs/README file as of 2019-02-19:

  • libxml2
  • libxslt [Debian packed the required xsltproc in a separate package,
which depends on libxslt]
  • docbook-xsl
at runtime
yelp (for viewing under linux)
Optional
  • gnome-doc-utils (contains xml2po for the use of po editors like in the it translation)
by target format
Mobipocket
chm (old fashioned Windows Help)
PDF
  • Apache fop >= 0.95
For non-latin scripts
  • Fonts. For the Japanese PDF, Japanese fonts are included. If you want to use other Japanese fonts you can use the --with-japanese-fonts-dir, --with-japanese-mincho-ttf, and --with-japanese-gothic-ttf configure options to select them. fop's TTFReader can't, as of version 1.1 anyway, handle OpenType fonts.

Note for wiki editors: Keep above section in sync with gnucash-docs/README

Other Operating Systems

Wm says the section below is being edited and not yet complete, see the thread "Help with help" in gnucash-devel for more info


macOS

At present we do not know of a suitable DocBook file toolset for macOS though a *nix on Mac approach may / should work. We encourage solutions so if someone could document this we would be grateful [Wm: aside is this redundant? Don't most modern Macs include *nix so instructions similar to those I have provided for Win might apply?]

Windows

One way of being able to edit and produce DocBook files on Windows is to use the *nix instructions under cygwin. Instructions for obtaining a suitable toolset follow

  • Get cygwin by going to https://www.cygwin.com and pressing the link for the setup-*.exe file suited to your system
  • save it, virus scan it, etc. as you see fit then run it
  • type "libxslt" into the search box
  • expand Libs and press Skip so that it shows a version for all 3 GNOME XSLT Library options, you want the most recent which it will offer by default, cygwin will work out the gndependencies
  • you may follow similar steps to obtain git, i.e. type "git" into the search box, expand and tick the obvious candidates
  • Note: because these are *nix type text based utilities you are downloading hundreds of kiloBytes not megaBytes; relax, this isn't Windows Update, a few extra progs won't kill your system, promise
  • click next at the bottom rhs and let cygwin do its stuff; this may take some time depending on connection speeds at both ends
  • Aside: if you get a msg about "Package: Unknown package / inetutils.sh exit code 1" you may ignore it, after reading the full blurb, of course, my advice is not to try and track it down unless you have a lot of spare time on your hands
  • When it is done fire up cygwin and do stuff as per the *nix instructions

Further details:

  • don't look for
  • yelp (the viewer)
  • on cygwin: it isn't there; it is an old prog (last updated in 2007, I think
wrong, see https://download.gnome.org/sources/yelp/ for the origin and https://cygwin.com/packages/summary/yelp.html for cygwin. --Fell 17:21, 26 October 2013 (EDT)
) and should probably not be regarded as current though it may be useful if you have it on another OS
[Wm:
  • I wonder how many current *nix users have it?
AFAIK it is still part of the GNOME desktop: google search for yelp+gnome --Fell 17:21, 26 October 2013 (EDT)
Should ref to yelp be made less prominent?
It is the only way I know to get some context sensitive help from inside GnuCash. --Fell 17:21, 26 October 2013 (EDT)
]

Wm says the section above is being edited and not yet complete, see the thread "Help with help" in gnucash-devel for more info

Java (all OS)

Eclipse has

  • several Git plugins,
  • a C Development Tool with Cmake support,
  • a feature rich, builtin XML editor and a few plugins like XML WYSIWYG editors

or in other words, all what is needed here, available.

The Procedure

Note
The procedure explains what needs to be done to add a new translation to the guide. If you want to add a new translation for the manual, make the following replacements:
Place Component
source directory name guide manual
document name gnucash-guide gnucash-manual

First, you have to download the most recent version of the gnucash-docs package. This is done as follows:

  1. Checkout the documentation in a directory gnucash-docs:
    git clone ${URL} -b stable gnucash-docs
    
    with ${URL}=https://github.com/Gnucash/gnucash-docs
  2. Create your working branch. If you plan to use pull requests, you should use unique names like LL-guide-chapter-x-part-n instead of working-branch.
    git checkout -b working-branch
    
    If this is the first GnuCash document in your language
    1. Create a new directory (if it doesn't already exist) as <locale> where <locale> is of the form <language>[_<region>] e.g. es, en_GB, or pt_BR. See #Naming Conventions and Locale_Settings#IETF_language_tags:
      LOCALE=LA # Replace Latin by your languages code
      mkdir -p ${LOCALE}
      
      If your translation is the first for your language do not append a region code. So also other regions benefit from your translation.
    2. Copy C/CMakeLists.txt into your ${LOCALE}/ directory and inside ${LOCALE}/CMakeLists.txt
      1. adjust the locale string in the first line of this file to match your directory name;
      2. adjust the following two lines (the ones starting with add_directory). Prepend both with a # sign. That will disable these documents in your language for now. We'll re-enable them as we add the proper document directories later on.
    3. In CMakeLists.txt in the toplevel of your source directory add an add_subdirectory entry for your language. The format is
      add_subdirectory(${LOCALE})
      
      Attention
      Replace ${LOCALE} by its content here.
      There are other examples in that file you can follow.
      Please keep the language list sorted alphabetically.
    4. Create a localized dtd
      It should primary contain the localization of the program's GUI elements like menu entries and is used in many places.
      1. cp dokbook/gnc-gui-C.dtd dokbook/gnc-gui-${LOCALE}.dtd
        
      2. Localize its content. Example: The first enry is docbook/gnc-gui-C.dtd#L25-L26
        <!-- File-Menu -->
        <!ENTITY % gm.file "<guimenu><accel>F</accel>ile</guimenu>">
        
        Replace Docbooks <accel>F</accel> by Gnomes gettext convention _F and search in the program's po file of your language for the string "_File" i.e. zh_CN.po#L27145-L27147
        #: gnucash/ui/gnc-main-window.ui:8
        msgid "_File"
        msgstr "文件(_F)"
        
        Convert the msgstring in the other direction and store 文件(<accel>F</accel>) as value of gm.file in gnc-gui-zh.dtd. You can fasten that by using
        $ msggrep --msgid -e '_File' po/zh_CN.po
        # GnuCash PO file, for Simplified Chinese.
        [–]
        
        #: gnucash/gtkbuilder/dialog-doclink.glade:276
        msgid "Linked _File"
        msgstr "本地文件(_F)"
        
        #: gnucash/ui/gnc-main-window.ui:8
        msgid "_File"
        msgstr "文件(_F)"
        
        #: gnucash/ui/gnc-plugin-basic-commands.ui:6
        msgid "New _File"
        msgstr "新建(_F)"
        
        in you programs top source directory. Continue with the next entry …
      Perhaps someone would provide a script?
    5. Copy the guide directory from C (English language) into this directory:
      cp -r C/guide ${LOCALE}/guide
      
      For languages that don't use latin characters
      They need additional files to process printing to pdf. See ja, ru, or zh as examples.
    6. Tell your documents to use your localized dtd:
      cd ${LOCALE}/guide
      for i in *.dokbook; do sed -i "s/gnc-gui-C.dtd/gnc-gui-${LOCALE}.dtd/" $i; done
      for i in *.xml; do sed -i "s/gnc-gui-C.dtd/gnc-gui-${LOCALE}.dtd/" $i; done
      cd ../..
      
    7. Notify git about the new directory and files. "*" is quoted by "\".
      git add ${LOCALE}/CMakeLists.txt ${LOCALE}/guide/\*.\*
      
      or
      git add ${LOCALE}/CMakeLists.txt ${LOCALE}/manual/\*.\*
      
  3. Now the real work:
    1. Edit index.docbook and all the xml files (see #DocBook xml editors below for suitable editor programs) and translate them into your language.
      • In the event the english documents get updated, it might be useful to have a comment in the header of each chapter in the form:
      <!-- Translation based on {stable|future} branch, commit 1234567 2023-01-01 10:00 UTC -->
      
      Then you can later view a diff between the current and that version of the english file in one window to locate the changes and adjust the translation in another window. Some translators like to do also the translation in a graphical diff program like KDiff3 between english and their language because the <sectN id>s will synchronize the text.
      Use consistent terminology
      Program's Glossary
      If you did not Translation#Get_the_source_from_Git, you can simply download your languages .po file from
      Verify its completeness and use its content in your translation. If it is not complete, update it according Translation#The_glossary_file.
      Guide's Glossary
      Verify that you have a recent version of C/guide/gnc-glossary.xml in your languages subtree and translate it—also for your later use.
      Use existing entities
      See Documentation_Improvement#Conventions
      Familiarize yourself with the global entities
      They are defined in docbook/gnc-docbookx.dtd
      Localize the GUI entities
      run Gnucash in your language and adjust the GUI elements in a copy from docbook/gnc-gui-C.dtd into docbook/gnc-gui-${LOCALE}.dtd.
    2. There are some general headers, which do not appear in the xml-files in your locale directory. But they can be translated by adding a section in xsl/l10n.xml. Obey the comment at the beginning. If you use non-ASCII characters, you should run recode -d <input_encoding>..h0 l10n.xml, where input_encoding might be u8 for UTF8, to get them right encoded. Obsolete?
    3. In addition to the text, you need to recreate the image files in C/guide/figures so that they are appropriate to your language. For details (size, style,...) see Documentation_Update_Instructions#Screenshots And Other Images.
      1. Most of them are screenshots of a gnucash session - save them as png files because this will use a lossless compression. In theory some of the files in gnucash/doc/examples could be a starting point therefor, but they are currently - 2010-09-17 - broken.
      2. A few figures are in scalable vector graphic (svg) format. Here you can edit the files e.g. in Libre/OpenOffice and translate the strings and adjust the size.
    4. Watch out: The documentation itself is probably outdated in many places, as it has been written for the 1.8.0 version of gnucash. You can watch the current progress in Concept_Guide#Ongoing_work. If you encounter any description that is wrong for the current version of gnucash, do not hesitate to ignore the english original text and instead describe the situation of the current version of gnucash in your translation. It would be even better if you have the time to change the english original text as well, or at least file a bug against it, but even if you can't do that, feel free to describe the actual state of gnucash in your translation and simply ignore the original english text.
      If you file a patch against the english text, you can also file a patch, which adds your name and email address to AUTHORS, so you will become famous. ;-) Ask to apply this latter patch also against gnucash/DOCUMENTERS because both files should have the same content. More details about editing the english text can be found in the Documentation Update Instructions.
  4. Test your xml files for syntax errors by running xmllint on the main file index.docbook, e.g.:
    cd ${gnucash-docs-dir} # adjust to navigate to your local gnucash-docs source directory
    xmllint --postvalid --xinclude --noout --path docbook ${LOCALE}/guide/index.docbook
    
    The program xmllint is part of the package libxml.
    Tip: Some xml aware editors have a menu entry like validate to run this test though they will likely be missing the path to the docbook directory that holds our custom DTD.
  5. Other recommended testing and validation options include opening your files in yelp and proofreading in html or pdf format. These extra options require you to generate your translated documentation in the proper formats. How to do so is described in more detail in Documentation Update Instructions. Please refer to that page for further instructions.
    1. Repeat these steps until you're satisfied with the result.
  6. Update the branches of your local repo often:
    git checkout stable              # switch to the stable branch
    git pull --rebase                # update it
    git rebase stable working-branch # update working-branch
    git checkout working-branch      # switch back to working-branch
    
  7. Follow #Submitting your work direct to GnuCash.

Committers: If it builds fine, add the directory changes from 2. also to gnucash/stable/packaging/win32/install-impl.sh and merge the change to future, if it exists and they are required there.

DocBook xml editors

For editing these DocBook xml files, various editors can be used: https://en.wikipedia.org/wiki/DocBook might contain pointers to some, or also https://www.tldp.org/LDP/LDP-Author-Guide/html/tools-edit.html.

Some developers use Eclipse.
The [german wikipedia says the translation tool OmegaT can work on docbook.

People have said that AbiWord and OpenOffice / LibreOffice have support for DocBook available, in which case you could directly edit gnucash's xml files with those. However, those editors will probably not work with the current multi-file setup where each chapter is in a separate XML file and the main XML file contains points to the chapters' files. As a workaround, you can copy the relevant parts of the main XML file into the chapter's file by a plain text editor so that it "looks like" one single DocBook document. This can be opened with OpenOffice/LibreOffice and edited as normal. After that, the added parts from the main file need to be removed again, and then you have the edited chapter text.

Using po editors

Some translators are more familiar with using po file editors like poedit, Kbabel, Gtranslator etc. For those people, it is possible to convert the content of the documents (the DocBook XML files) into po files, translate the messages in the po file, and convert the result back into xml. This section describes how to use this approach for the GnuCash documentation.

The downside of this approach
It will be much harder for the documenters to fix e.g. broken links in times where you are inactive.

In order to use po files you have first to convert xml files to po files, translate them and then convert back to xml.

Prerequisite
First you have to install a fresh version of gnome-doc-utils. For example in a Fedora 13 system:
yum install gnome-doc-utils
Other distributions might have split it as a separate [python-]xml2po package.
  1. Do the conversion with the following commands (${LL} is your language code, example: el for Greek):
    #Append your language code
    LL=
    # and the desired component {manual|guide}
    COMPONENT=
    # Create pot
    ## cd to get short references: 
    cd C/${COMPONENT}
    ## (it seems to reverse the order)
    ## if already translated xml files exist, specify them with -r
    xml2po -k -o ../../${COMPONENT}.pot *.xml index.docbook
    cd ../..
    # Create target directories
    mkdir -p ${LL}/${COMPONENT}/figures
    cp C/${COMPONENT}/CMakeLists.txt ${LL}/${COMPONENT}/
    cd ${LL}/${COMPONENT}
    # Create po
    ## If on behalf of others, append --no-translator
    msginit -l$LL -i../../${COMPONENT}.pot
    cd ../..
    
  2. Translate ${LL}.po using your favorite po editor.
  3. Convert back to xml:
    cd C/${COMPONENT}
      xml2po -p ../../${LL}/${COMPONENT}/${LL}.po -o ../../${LL}/${COMPONENT}/index.docbook index.docbook
    for i in *.xml; do
      xml2po -p ../../${LL}/${COMPONENT}/${LL}.po -o ../../${LL}/${COMPONENT}/$i $i;
    done
    cd ../..//${LL}/${COMPONENT}
    echo Do not add ${COMPONENT}.pot into git!
    
  4. Test your translated xml file as mention above:
    xmllint --valid --noout /${LL}/${COMPONENT}/index.docbook
    
    Now you still have to create the images.

GnuCash Maintainer Tasks

For new languages the core developers have some additional tasks:

New Script

Check
make pdf
Do we need additional TTFs?

First Nightly

Ask the admin of code.gnucash.org to create the new directory.

First Release

Adjust htdocs…