Perl module documentation language conventions

Polyglot has asked for the wisdom of the Perl Monks concerning the following question:

I realize that most Perl developers speak English, and English is the universal language of computing in general. However, there are Perl modules developed specifically to accommodate other languages. In those modules, are there any guidelines for POD, for README files, or for other documentation in terms of their language? Would it be frowned upon to have a bilingual documentation within a module targeting a non-English language?

EDIT: I should add that a part of this question stems from my own realization that to include bilingual documentation in a module I am developing would also necessitate the invocation of use utf8;, as the language is not one that uses the Roman alphabet.

Blessings,

~Polyglot~

Comment on Perl module documentation language conventions Download Code

Replies are listed 'Best First'.
Re: Perl module documentation language conventions by kcott (Archbishop) on Oct 23, 2023 at 14:40 UTC
G'day Polyglot, "EDIT: ... necessitate the invocation of `use utf8;` ..." In that case, I recommend you place the following directive at, or very near, the start of your POD: `=encoding utf8` [download] I always put that as the first line of POD in my modules. It means I don't have to worry about using borrowed words with diacritical marks anywhere in the POD. It also covers the following piece of boilerplate which appears near the end of the POD in most of my modules: =head1 LICENCE AND COPYRIGHT Copyright © ... See also: "perlpod: =encoding encodingname". — Ken	[reply] [d/l] [select]
Re: Perl module documentation language conventions by LanX (Saint) on Oct 23, 2023 at 14:00 UTC
Let me break it down into three aspects... formal rules and conventions I don't think there is generally any problem using another language especially if it's bilingual. I'm not aware of any hard rule here, and I'd been extremely surprised if using additional languages was forbidden. I'd be even surprised if anyone said that English was obligatory. Regarding convention: IMHO as a courtesy at least an abstract in English should explain the purpose. technical aspect Please note that adding extra .pod files in other languages and linking to them is easy°. And I'm sure I've seen distros with `module_en.pod` plus something like `module_de.pod` Legal issues There might have been a problem where spam, radical or criminal propaganda is embedded and can't be spotted/flagged on metacpan because the language is "exotic". But in the days of automatic translations this should be covered. And this would be an issue for the metacpan site and not CPAN in general. Cheers Rolf _{(addicted to the Perl Programming Language :) see Wikisyntax for the Monastery} Updates °) `perlpodspec` : > `... L<name> values are of two types: either the name of a Pod page like L<Foo::Bar> (which might be a real Perl module or program i +n an @INC / PATH directory, or a .pod file in those places` [download]	[reply] [d/l] [select]
Re^2: Perl module documentation language conventions by marto (Cardinal) on Oct 23, 2023 at 15:12 UTC
"But in the days of automatic translations this should be covered." From a few days ago.... It has also been a problem when the language was English (in so much that the stuff was/is on cpan/backpan).	[reply]
Re^3: Perl module documentation language conventions by LanX (Saint) on Oct 23, 2023 at 15:55 UTC
> has also been a problem when the language was English Well, in the age of AI censoring to assure political correctness this could be flagged too. (Sarcasm batteries included) (Tho, I'm not too sure about biological intelligence either, I remember the case of Romanian referees attacked at a champions league game for using the word "negru" which only means black in their language and shouldn't be measured by anglo Saxon standards) Cheers Rolf _{(addicted to the Perl Programming Language :) see Wikisyntax for the Monastery} update https://valahia.news/romanian-referee-black-negru-demba-ba/	[reply]
Re^4: Perl module documentation language conventions by soonix (Chancellor) on Oct 23, 2023 at 16:36 UTC
Re^5: Perl module documentation language conventions by LanX (Saint) on Oct 24, 2023 at 00:45 UTC
Re^2: Perl module documentation language conventions by Polyglot (Chaplain) on Oct 23, 2023 at 14:34 UTC
Regarding machine translations, that may still be somewhat of an issue outside of European languages. Asian languages differ so radically from European languages that any machine translation between them is of poor quality. It may suffice, for those languages where translation is available, to understand the main topic, but the details are unreliable (some keywords can be totally mangled). Use of idioms will reduce translation quality considerably, and a skilled linguist could potentially manipulate the machine translation to obscure the actual intent of the message. True, great strides toward improvement have been made in recent years, but there are still many shortcomings and languages for which no machine translation is available--for several of which (Karen, Shan, etc.) I am already in process of coding utilities. Regarding inclusion of non-Roman scripts in POD, there may be some encoding issues, especially for those unaccustomed to or unprepared for working with unicode fonts. Blessings, ~Polyglot~	[reply]
Re^3: Perl module documentation language conventions by LanX (Saint) on Oct 23, 2023 at 16:05 UTC
There are also issues between western languages because English is often the intermediate bridge language and lacks grammar. As an example: Most western languages differentiate between a respectful you and an intimate you (Vous/tu Sie/du Usted/tu ...) when addressing another person.° But Google translate will default to respectful, so "I like you" in French will become something like "Sir/Ma'am, I like you" in Spanish, which is weird when flirting. Cheers Rolf _{(addicted to the Perl Programming Language :) see Wikisyntax for the Monastery} °) on a side note the antiquated English "thou" is the direct translation for tu/du , so it's the informal you. But because people mostly know it from biblical texts, they think it's a respectful form. (Surprise: God doesn't respect you! ;) Bottom line: the old English from Beowulf would be a much better intermediate language for Indo European translations.	[reply]
Re^4: Perl module documentation language conventions by Polyglot (Chaplain) on Oct 23, 2023 at 18:11 UTC
Re^5: Perl module documentation language conventions by Jenda (Abbot) on Oct 24, 2023 at 14:28 UTC
Some notes below your chosen depth have not been shown here
Re: Perl module documentation language conventions by cavac (Prior) on Nov 02, 2023 at 14:12 UTC
In my opinion, a bilingual documentation should be just fine. For ease of use (and to prevent surprises), i'd specify right at the beginning that "the document is available in the following languages" and maybe state in a sentence or two where to find which language. It seems you technically don't even need to use proper english or characters that are used in any other language, thanks to the ability of UTF8 to combine stuff. I'm looking at you, Acme::Umlautify But in your case, making sure that english is one of the languages in the documentation would be very appreciated. Yes, the final use case might be limited to a certain region or language. But always think of the person that is hired to do the actual implementation of a project that uses your library (or, for that matter, maintain the software in years to come). They might be from a completely different part of the world. PerlMonks XP is useless? Not anymore: XPD - Do more with your PerlMonks XP	[reply]

Back to Seekers of Perl Wisdom