Wireshark-dev: [Wireshark-dev] Re: Persian (Farsi) translation of the Wireshark User's Guide 5.

Date Prev · Date Next · Thread Prev · Thread Next
Date: Sun, 15 Nov 2026 16:13:43 +0100
Hi all,

Following up on my message of November 12: Guy suggested using this
first documentation translation as an opportunity to design a general
way of handling such translations, and I offered to draft a short
proposal for the list to criticize and shape. Here it is. The Persian
translation is the pilot case, but the rules are written to cover any
language.

---

A general mechanism for Wireshark documentation translations — draft proposal

Background. The project's documentation has never had translations;
translation so far covers only the GUI, via Transifex. A complete
Persian translation of the User's Guide now exists, and rather than
handling it as a one-off exception, this draft proposes a small set of
general rules that would cover it and any future documentation
translation, in any language.

Principles.
1. The English guide is the only authoritative text. Translations are
community works that point back to it.
2. Zero burden on the English documentation maintainers. Every duty
below belongs to the translation's maintainer.
3. Honesty over coverage. A translation states plainly what it covers
and which English release it is based on.

The mechanism.
1. Listing. A qualifying translation is listed in one place —
proposed: the wiki's Translations page — with its language, base
English release, a link, and the maintainer's name and contact. It is
labeled a community translation, not an official release.
2. Qualification. To be listed, a translation must (a) cover the
complete guide for its stated base release; (b) be readable in its own
right, including correct text direction and the guide's images; and
(c) have a named, reachable maintainer.
3. Version pinning. Every page states its base English version; the
listing shows the same version.
4. Synchronization. On each new stable English release, the maintainer
diffs the AsciiDoc sources chapter by chapter and re-translates only
what changed — the Transifex model, batched per release. Target:
re-synchronization within one release cycle.
5. Staleness and delisting. Not re-synchronized after a new release →
marked outdated. Two releases behind, or maintainer gone without a
successor → removed from the listing.
6. Source format. The translation's source follows the guide's own
AsciiDoc structure (same file names and anchors as wsug_src), so
in-tree adoption later needs no reformatting. Hosting may remain
external; the project only links.
7. Terminology. Shared terms follow the project's GUI translations on
Transifex. Protocol names, display-filter syntax and field names stay
in English.
8. Licensing. Translations are derivatives distributed under the
guide's own license terms, with credit to the project and a link to
the English original.

The pilot. The Persian translation already operates under these rules:
complete for base version 5.1.0, every page version-pinned, hosted at
https://fa-userguide-wireshark.arianahmadi27.workers.dev/, with a
named maintainer, and the Preface, Chapter 1 and Chapter 4 maintained
in the guide's AsciiDoc format as a sample. Where the rules are wrong,
the pilot is a concrete case to correct them against.

Questions for the list.
- Are the staleness thresholds (mark after one missed release, delist
after two) the right ones?
- Is the wiki Translations page the right listing place, or should
listings live on the website?
- Is link-only the right long-term posture, or should this aim at
in-tree AsciiDoc once a translation has survived a few release cycles?

---

And one smaller request from my earlier reply, still open: while the
mechanism takes shape, could a temporary link to the Persian site be
added from the wiki Translations page?

Thank you,
Arian Ahmadi

On Thu, 12 Nov 2026 10:48:08 -0800, Guy Harris <gharris@xxxxxxxxx> wrote:
> On Nov 12, 2026, at 10:10 AM, arianahmadi27@xxxxxxxxx wrote:
>
> > What I would appreciate is your guidance on the route you prefer:
> >
> > 1. If there is interest in an officially hosted or in-tree Persian
> > guide in the future, what format and review process would you like me
> > to follow, starting from the AsciiDoc sample?
>
> Are there any *other* translations available for the Wireshark documentation?
>
> If so, how are *they* handled?
>
> If not, perhaps this should be used as an opportunity to come up with a general way of handling them?
>
> One issue is that translating a manual is a *lot* more work than translating GUI elements and messages. We currently handle the latter by having developers change only the text in the Wireshark source and, presumably, expecting the translators for particular languages to pick up those changes and update the translations. The same issue would exist for the Wireshark documentation as well.
> _______________________________________________
> Wireshark-dev mailing list -- wireshark-dev@xxxxxxxxxxxxx
> To unsubscribe send an email to wireshark-dev-leave@xxxxxxxxxxxxx