<!-- vim: set tw=78 sts=2 ai expandtab: -->
# Translation of debian-reference (weblate.org)

2026-08-15T01:53:37+00:00

Osamu Aoki, &lt;osamu at debian dot org&gt;

See [README.md](README.md) for general guide of the `debian-reference` source.

See [po_completed.md](po_completed.md) for the translation status.

## Basics

"Debian Reference" offered as the debian-reference source package has many
published translations as web pages and Debian packages.

* https://www.debian.org/doc/user-manuals#quick-reference
* https://tracker.debian.org/pkg/debian-reference

In order to make translation work as easy as possible, the debian-reference
package accepts translations indirectly from the weblate.org service.

(Please note that the direct translation update of the upstream PO files at the
salsa.debian.org GIT service using PR mechanism is more preferred method.)

I recognize that the use of the salsa.debian.org GIT service is non-trivial
for most translators.  So I don't force this burden to translators. Instead, I
encourage translators to use the weblate.org service.  After all, the **GOAL**
is offering better translations.

Currently, following languages use the direct translation update method at
salsa.debian.org and the weblate.org service skips translations for.

* ja (Japanese)
* it (Italian)
* de (German)

Currently, debian-reference project at the weblate.org service is managed by:

* Xiao Sheng Wen, &lt;atzlinux at debian dot org&gt; (main)
* Osamu Aoki, &lt;osamu at debian dot org&gt; (sub)

You may send a mail to these maintainers while CC-ing debian-doc@lists.debian.org asking their actions.

Mails to debian-doc@lists.debian.org is archived at https://lists.debian.org/debian-doc/

## How to translate via weblate.org

### Sign in to your account on weblate.org

* With your browser, open https://hosted.weblate.org
* Click "Register" (if you don't have an account) or "Sign in" (if you already
  have an account)

### Update existing translations

* Go to https://hosted.weblate.org/projects/debian-reference/
* Update your choice of translations using web UI

Please follow following rules when translating.

* Don't use `%` character in the translation of the URL string
  * Service at https://www.urldecoder.io/ can help to decode the URL string
    containing `%` copied from the browser bar to the desirable UTF-8 string.
  * Most wikipedia pages have link to the translated text at the left of web page.
    * `msgid "https://en.wikipedia.org/wiki/Character_encoding"`
    * `msgstr "https://fr.wikipedia.org/wiki/Codage_des_caractères"`
* Don't use `&` character for `&` in the translation of the URL string
* Don't translate XML markups. For example:
  * `<ulink url=\"&debianreferenceversiondrversion;\">`
  * `</<ulink>`
  * `<literal>`
  * `</literal>`
  * `<emphasis role=\"strong\">`
  * `</emphasis>`
  * `<xref linkend=\"_backup_and_recovery\"/>`
* Don't translate placeholder markers: `@-@popcon1@-@`, ...
* Don't translate the string marked up with `<literal>....</literal>`
  * You may see string such as `<literal>foo</literal>` as a part of msgid.
    If `foo` in your language means `bar`, please translate this part of msgid
    as: `<literal>foo</literal> (bar)`.  This is because `foo` here is a
    literal string matching the string in the configuration file etc.
  * If an entire translation string (msgid) is in the form of
    `<literal>...<literal>`, the corresponding translated string (msgstr) will
    be overwritten by the weblate.org with msgid-string as "Fill read-only
    strings with source".

Please note the translation result stays on the weblate.org service until upstream
maintainers merge them to salsa.debian.org manually after rigorous sanity
checks.

### Request for a new language to translate

If you don't see your language at the weblate.org service of debian-reference
please request its addition.

* Use the web UI at https://hosted.weblate.org/projects/debian-reference/ and
  click `+` at the top row next to "Language".
* You may need to wait for the maintainer to process your request.

This "Debian Reference" requires translation of over 6000 strings.  Until a
translation reaches reasonable completion (about 40% or more), it will not be
published.

## Notes for the upstream operation

**This section is not for translators.**

### Update language filter

* Method 1: Click "Components" tab -> Select "Translations" component -> "Operations" tab -> "Settings" pull-down menu -> "Files" tab:
* Method 2: Click "Operations" tab -> "Settings" pull-down menu -> "Components" tab -> Click "Translations" -> "Files" tab:
* One of the 2 methods lands on https://hosted.weblate.org/settings/debian-reference/translations/#files
* Update "Language filter" entry (See https://docs.weblate.org/en/latest/admin/projects.html#component-language-regex )

### Update announcement

* Click "Operations" tab -> "Post announcement" pull-down menu
* Update "Message" entry (See https://docs.weblate.org/en/latest/admin/announcements.html )

### Merging weblate.org to salsa.debian.org

Merging of weblate.org contents to salsa.debian.org is performed roughly as:

```sh
git clone git@salsa.debian.org:debian/debian-reference.git
cd debian-reference
git config set pull.rebase true
git remote add weblate https://hosted.weblate.org/git/debian-reference/translations/
git remote update
wlc repo
wlc commit
git pull weblate latest
... fix merge and translation errors and commit to "latest" branch
git push
wlc pull
```

(See more detailed setup and use case for maintaining salsa.debian.org GIT
repository at [README.md](README.md) and [README_salsa.md](README_salsa.md)

### Add a new language on salsa.debian.org

To add a new language, e.g., "ta" to a checked out salsa.debian.org
repository:

```sh
cd po
cp debian-reference.pot ta.po
cp en.tex ta.tex
git add . -m "Add ta"
```

NOTE: You can also add translation only content using `ta.add` and similar.

### How to check weblate repository status

Execute `wlc` in checked out source as:


```
 $ wlc repo
needs_commit: True
needs_merge: False
needs_push: False
url: https://hosted.weblate.org/api/projects/debian-reference/repository/
```
