How to build translated versions?

[LukeLR]

Thanks a lot for this awesome documentation for Nextcloud. By following the documentation in README.rst I was able to successfully build both the HTML and the PDF version locally.

However, I wanted to build a PDF of the german version to provide it in a translated version of the Nextcloud skeleton folder. I can see that the repository contains translated strings in user_manual/locale, but I couldn't find any documentation on how to build a translated version of the manual from this.

Maybe some instructions for building translated versions could also be added to the README.rst? Or is that documented somewhere else? Then we could maybe point to that external documentation? Thanks a lot in advance!

[pierreozoux]

@LukeLR

I think you need to mix these 2 commands: https://github.com/nextcloud/documentation/blob/master/user_manual/Makefile#L60 https://github.com/nextcloud/documentation/blob/master/user_manual/Makefile#L130

If you found the solution, other people would be happy to know :)

[rhabacker]

At least under openSUSE Leap 15.5, the main problem with creating translated documentation is that this project contains .pot files in locale/<language> subdirectories, but gettext requires .po files (https://www.gnu.org/software/gettext/manual/html_node/Overview.html). You can see this by the fact that when building the documentation with

cd ~/src/documentation/user_manual
make html-allow-warnings-lang-en
sphinx-build -b html -D html_theme='sphinx_rtd_theme' -D language=en -d _build/doctrees . _build/html/en
Sphinx v7.2.6 in use
Loading translations [en]...done
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
reading sources... 
looking for now-outdated files... none found
no targets are out of date.
build completed.

the listed number is 0.

I have built a shell script to create the required files:

#!/bin/sh
for i in $(find -type f -name '*.pot'); do
    (
        cd $(directory name $i)
        n=$(basename $i)
        ln -fs $n $(echo $n | sed 's,\.pot,.po,g') 
    )
done

After running the script, I get a German documentation after rerunning the same command as mentioned above:

cd ~/src/documentation/user_manual
make html-allow-warnings-lang-en
sphinx-build -b html -D html_theme='sphinx_rtd_theme' -D language=de -d _build/doctrees   . _build/html/de
Sphinx v7.2.6 in Verwendung
Lade Übersetzungen [de]…erledigt
loading pickled environment... erledigt
building [mo]: targets for 50 po files that are out of date
writing output... [100%] locale/de/LC_MESSAGES/pim/sync_osx.mo
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 39 changed, 0 removed
reading sources... [100%] whats_new
/home/ralf.habacker/src/documentation/user_manual/files/access_webdav.rst:20: WARNING: inconsistent references in translated message. original: [], translated: ['`Nextcloud-Sync-Clients <https://nextcloud.com/install/#install-clients>``_']
/home/ralf.habacker/src/documentation/user_manual/files/access_webdav.rst:20: ERROR: Unknown target name: "nextcloud-sync-clients <https://nextcloud.com/install/#install-clients>`".
/home/ralf.habacker/src/documentation/user_manual/groupware/contacts.rst:168:<translated>:1: WARNING: Inline strong start-string without end-string.
/home/ralf.habacker/src/documentation/user_manual/groupware/contacts.rst:168:<translated>:1: WARNING: Inline strong start-string without end-string.
/home/ralf.habacker/src/documentation/user_manual/userpreferences.rst:64:<translated>:1: WARNING: Inline strong start-string without end-string.
/home/ralf.habacker/src/documentation/user_manual/userpreferences.rst:64:<translated>:1: WARNING: Inline strong start-string without end-string.
looking for now-outdated files... none found
pickling environment... erledigt
checking consistency... erledigt
preparing documents... erledigt
copying assets... copying static files... erledigt
copying extra files... erledigt
erledigt
writing output... [100%] whats_new
generating indices... genindex erledigt
writing additional pages... search erledigt
copying images... [100%] images/multi_sharing.png
dumping search index in German (code: de)... erledigt
dumping object inventory... erledigt
build abgeschlossen, 6 warnings.

building [mo]: targets for 50 po files that are out of date