Wireshark-dev: [Wireshark-dev] Re: Persian (Farsi) translation of the Wireshark User's Guide 5.
From: arianahmadi27@xxxxxxxxx
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
- References: