Hi Guy,
Thank you for the quick reply, and for raising exactly the right questions.
On other translations: to my knowledge, there are none for the
documentation. As far as I could determine before starting, no
translation of the User's Guide (or the Developer's Guide) exists in
any language — neither officially hosted nor handled by the project in
any way. Translation in the project so far covers the GUI, via
Transifex. If anyone on the list knows of a community documentation
translation I have missed, I would genuinely like to hear about it,
because I had nothing to model this on.
That is also why I like your suggestion: if this is the first one, it
makes sense to use it to design a general way of handling
documentation translations, rather than inventing a one-off exception
for Persian. I am happy for this translation to be the test case, and
I am also happy to write up a short proposal for such a mechanism —
scope, synchronization model, staleness rules, hosting/listing options
— for the list to criticize and shape.
On the synchronization issue, which I agree is the core problem: a
manual is not a string table, and nobody can re-translate a book on
every commit. The model I am working to, and would propose for the
general mechanism, is:
1. Version pinning. The translation is pinned to a specific English
release (currently 5.1.0), and every page states the version it is
based on. The English guide is always the authoritative text.
2. Release-cycle synchronization. When a new stable release of the
guide appears, I diff the English AsciiDoc sources chapter by chapter
and re-translate only what changed. That is the same "translators pick
up the changes" model as the GUI, batched per release instead of per
commit, which keeps it feasible for one maintainer.
3. Honest staleness. Until a chapter has been re-synchronized, it
keeps displaying its actual base version — a translation that lags is
never silently presented as current. A general mechanism should
probably go further and define what happens to a translation that
falls too far behind or loses its maintainer (marking it, or delisting
it), so the project is never stuck hosting something abandoned.
4. Zero burden on the English documentation maintainers. All of the
above is the translator's job, not yours. If a translation creates
work for the English side, I would consider that a defect in the
mechanism.
For the format question from my first message: I already have the
Preface, Chapter 1, and Chapter 4 in the guide's own AsciiDoc format,
with the original wsug_src file names and anchors, if seeing them
would help judge how a translated guide could sit alongside the
English sources. I can send them to the list or to any reviewer who
wants a look.
One practical request in the meantime, while a general mechanism is
being discussed: would you be willing to link to the Persian site —
for example from the wiki's Translations page — as a community
translation? It would give this discussion a concrete worked example
to point at, including the right-to-left presentation and the version
pinning; it costs the project nothing; and it can simply be adjusted
or removed once a general mechanism exists and defines how such
translations should be referenced.
Would it be useful if I drafted that one-page proposal for a general
documentation-translation mechanism as a starting point for
discussion?
Best regards,
Arian Ahmadi
GitHub: AlefAhmadi
Persian User's Guide: https://fa-userguide-wireshark.arianahmadi27.workers.dev/
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