Translation of the darktable documentation is done via our Weblate instance .

You can either use Weblate’s web UI to translate the documentation or download the translation from Weblate to your computer, edit it, and then upload the changes.

Please do all translation work through Weblate. We will not accept pull requests directly on github to update PO files.

Making a new branch in git

  1. Make a new branch to work on it in git. For example: git checkout -b fr-translation-init

Adding a new language to Hugo

  1. In the files config.yaml and config-pdf.yaml, locate the languages: line.
  2. Add the language you wish to translate. For example, the English looks like this:
    1  en-us:
2    title: darktable 3.4 user manual

date: 2022-12-04T02:19:02+01:00 weight: 1

 1
 23. Save the files.
 3
 4## Generating a PO file
 5
 6Do the following steps if you want to update the POT and PO files from the markdown source.
 7
 81. Create an empty PO file for your language in the `po` folder with the file name `content.<language>.po`.
 9For example:
10`touch po/content.fr-fr.po`
112. Run the script to populate the PO file:
12`cd tools/ && ./generate-translations.sh --no-translations`
13
14## Generating translated files
15
16Do the following steps to generate the website files from a translation.
17
181. Generate the translated files:
19`cd tools/ && ./generate-translations.sh --no-update`.
202. Check the translation by starting hugo's internal server:
21`hugo server`
223. Open a web browser and check the changes. The URL is in the output of the `hugo server` command.
234. Remove the translated files, as we never check them into git:
24`cd tools/ && ./generate-translations.sh --rm-translations`.
25
26## Translating website, epub, and PDF strings
27
28There are two themes for the darktable documentation: one for the HTML website and one for the PDF. You'll need to translate the strings for both.
29
301. Go to `themes/hugo-darktable-docs-themes/i18n`.
312. Copy content of the file `en.yaml` and name the new file `<your language>.yaml`.
323. Translate the content of the new yaml file.
334. Check the translated PO file into git, push it to github, and open a pull request to have your changes accepted.
345. Repeat the last four steps for the other themes, `themes/hugo-darktable-docs-epub-theme` and `themes/hugo-darktable-docs-pdf-theme`.
35
36## Integrating new translations from Weblate
37
38The following assumes that you're git working directory is clean, that you have API access to the Weblate instance, that you've configured the Weblate git repo as a remote in your local `dtdocs` git repo, and that `wlc`, the Weblate command line client, is configured.
39
401. Commit any changes in Weblate: `wlc commit darktable/dtdocs`
412. Lock the Weblate project to prevent further changes: `wlc lock darktable/dtdocs`
423. In your local `dtdocs` git repo, create a new branch: `git checkout -b po-updates`
434. Update the Weblate remote: `git remote update weblate`
445. Merge the Weblate changes into your locally created branch: `git merge weblate/master`
456. Squash all the Weblate commits, since there are so many: `git reset $(git merge-base master $(git rev-parse --abbrev-ref HEAD))`
467. Stage the changed PO files: `git add -A`
478. Commit the `PO` files: `git commit -m "Updated with the PO files from weblate."`
489. Update the `POT` and `PO` files: `cd tools/ && ./generate-translations.sh --no-translations && cd ..`
4910. Stage the `POT` and `PO` files: `git add -A`
5011. Commit the `POT` and`PO` files: `git commit -m "Updated POT and PO files."`
5112. Create a Pull Request in Github.
5213. After the Pull Request is accepted, reset the Weblate repo to match the `dtdocs` repo: `wlc reset darktable/dtdocs`