Translation docs and workflow

[Marek Marczykowski-Górecki]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Hi all,

Few days ago I had very interesting conversation about translating our
documentation, where a lot of important questions were asked. With
Tobias's permission, I post it here for discussion:

> ## Concerns concerning necessary instructions for translations.
>
> Hello,
>
> I have some questions whose answers I need to
> understand how to translate the Qubes OS contents you
> uploaded to Transifex into e.g. German. Since I
> couldn't find any instructions on how to translate
> these quasi-Markdown files, I'm asking this way.

Those files are in github-flavored markdown. You can read more about it here:
https://help.github.com/articles/basic-writing-and-formatting-syntax/
https://help.github.com/articles/configuring-jekyll/#front-matter-is-required

> I have 4 concerns.
>
>
> 1)
> The last entry concerning the issue [1] points out that
> all file names shall remain untranslated while all
> paths have to be preceeded with a "/de" (in case of
> German). Is that correct?
>
> Thus, the Git repository file
> "/qubes-doc/reference/vm-tools.md" has to be translated
> from
>
> =====================================================================
>
> ---
> layout: doc
> title: VM Tools
> permalink: /doc/vm-tools/
> redirect_from:
> - /en/doc/vm-tools/
> - /doc/VmTools/
> - /wiki/VmTools/
> ---
>
> VM tools:
>
> - [qvm-copy-to-vm](/doc/vm-tools/qvm-copy-to-vm/)
> - [qvm-open-in-dvm](/doc/vm-tools/qvm-open-in-dvm/)
> - [qvm-open-in-vm](/doc/vm-tools/qvm-open-in-vm/)
> - [qvm-run](/doc/vm-tools/qvm-run/)
>
> =====================================================================
>
> to
>
> =====================================================================
>
> ---
> layout: doc
> title: VM-Werkzeuge
> permalink: /de/doc/vm-tools/
> redirect_from:
> -
> - /de/doc/VmTools/
> - /de/wiki/VmTools/
> ---
>
> VM-Werkzeuge:
>
> - [qvm-copy-to-vm](/de/doc/vm-tools/qvm-copy-to-vm/)
> -
> [qvm-open-in-dvm](/de/doc/vm-tools/qvm-open-in-dvm/)
> - [qvm-open-in-vm](/de/doc/vm-tools/qvm-open-in-vm/)
> - [qvm-run](/de/doc/vm-tools/qvm-run/)
>
> =====================================================================
>
> Is that correct? (Please compare line-by-line, since
> Transifex forces to translate this way.)

Yes, that's right.

> 2)
> Within the interactive translation tool of Transifex,
> there is a tag named "notranslate" for some phrases.
> What does it mean?

https://docs.transifex.com/live/webmasters#how-to-handle-non-translatable-content

A phrase that should not be translated. So, from those options below I'd guess "c", but not sure - maybe transifex automatically copy original text in that case, so it doesn't matter? Anyway "c" sounds like the safest option.

> Here are some possible answers I
> found by thinking about it:
>
> a) I may ignore these phrases altogether, because they
> will be translated automatically afterwards. (But why
> do they appear here anyway? That's annoying.)
>
> b) I have to "Save" the phrase. The content in the
> field for the translated phrase doesn't matter. (This
> could be confusing.)
>
> c) I have to copy the original phrase as a whole to the
> field for the translated phrase, thus both strings will
> match exactly.
>
> d) I have to leave the field for the translated phrase
> blank. (But this looks like the line is going to become
> empty in the resulting Markdown file or vanish at all,
> maybe resulting in strange errors.)
>
> After having written down this second concern, I found
> out by chance that the tag "notranslate" means solution
> c) (see the warning signs in "intro.txt"). But it's
> confusing that empty strings are accepted as a
> "notranslate"-translation (see "vm-tools.txt", for
> example).
>
>
>
> 3)
> What about special rules for Markdown or the webserver
> or something? Or just for keeping the md-files
> good-looking? For example the number of underlining
> "="s for a section title. Or the "redirect_from"
> directive? Or special characters that might not be
> allowed in Markdown?

Take a look at links I put above.

> 4)
> How to translate special terms? I'd like to open and/or
> see discussions if needed. (For that, I don't want to
> need a Google account.)

This should be better discussed on qubes-devel mailing list: https://www.qubes-os.org/mailing-lists/#qubes-devel
You do not need a google account for it.

> Summarizing my concerns:
>
> In my view, it would be very handy and helpful to
> provide an instructions page showing the necessary
> rules on how to translate and what to consider for
> gaining unbroken and well-functioning Markdown files.
> Note that translators who don't know that these phrases
> are parts of Markdown files could accidently break
> those files. Also note that not everybody is
> well-trained in editing Markdown files, knowing
> specials rules (like "redirect_from" directives and
> "/paths/to/someting/", constant_filenames) and anything
> else like that.

This is indeed a good idea. Maybe it should be just additional section here: https://www.qubes-os.org/doc/doc-guidelines/ ?

> I can imagine that the lack of such an instructions
> page is a good reason why the translation progress is
> (in my view) quite low. For example, when I opened the
> resource "vm-tools.txt" for translating it into German,
> the only one phrase translated yet was (and still is)
> "redirect_from:", translated via TM as
> "umgeleitet_von:", probably resulting in strange errors
> in the end. Other files seem to be well-translated, but
> strings like "=======================" have just been
> copied or haven't been translated at all. See
> "intro.txt" for example.
>
>
> I hope that I could help you with that. If I'm totally
> wrong then it's also okay for me. The only aim for me
> is to help you.

Thanks!

> Kind regards,
> Tobias



> ## Re: Concerns concerning necessary instructions for translations.
>
> Hello Marek,
>
> I generally agree with you. Thank you for the links. And also much thanks for reading my big message. Once more, I have a big message here. I hope that this is okay for you.
>
>
> I've found some new concerns to consider. They should be solved and written down into a documentation as you mentioned here:
>
> > This is indeed a good idea. Maybe it should be just additional section here: https://www.qubes-os.org/doc/doc-guidelines/ ?
>
> I could help you and write that additional section, if you like. (... using my best English I ever had.)
>
>
>
> 5) As mentioned in the summary in my last e-mail, clarify that these *.txt files are in fact YAML/Markdown files and thus, they have to be translated carefully. Provide the links to the grammars you sent me. Remind the translators to pay attention to the differences between accents, apostrophs, quotes and backticks and so on.
>
> 6) Does the translator has to address formally or informally? (E.g. "you" can be translated into German with either "du" (informally) or "Sie" (formally).)
>
> 7) What is the general tone? Rather formal? Rather slang?
>
> 8) What are the names to use for the language directories? ("/en", "/de", "/es", ...) They should be defined.
>
> 9) How to treat underlinings for section names? "============". The Transifex feature "TM Autofill" is not convenient here, since the number of "="s depend on the individual, preceeding lines. See also points 3) and 14).
>
> 10) On the basic Markdown syntax page you sent me [1], I've found that relative paths are also allowed (I'm not sure if this will also work with Jekyll). Thus, we could use something like "./qvm-run/" instead of "/de/doc/vm-tools/qvm-run/" or "/es/doc/vm-tools/qvm-run/". This has great advantages since many paths don't need to be adapted. Precondition is that the original paths are also relative ones. See also step #2 below.
>
> 11) Do HTML anchors (#here) have to keep their names when translating? (I guess "yes".)
>
> 12) What is the better guideline? Translating special terms (like "TemplateVM" or "usbVM") into the individual target language or just copying them, remaining untranslated? The former may result in confusions and discussions while the latter is easier to implement and may help when asking for help in English or consulting English-speaking screenshots (I prefer the latter).
>
> 13) -deleted-
>
> 14) Depending on the context, equally written expressions may differ in semantics and translation. E.g. "I read this book." can happen in the present or the past, therefore, it's ambiguous. As I guess, the Transifex feature "TM Autofill" is enabled for this project and could lead to strange errors and mistakes in the end. I suggest to turn off that feature if possible.
>
> 15) Beautify the original md-files before copying them to Transifex. E.g. some sentences are spread over several lines, therefore, translations of such a partial sentence might fit here, but not there. An example file is "templates.txt". This may become a problem in combination with 14). Also in the source text files, some sentences are written in a single line in common. E.g. in "system-requirements". See also step #2 below.
>
> 16) Problems with leading and trailing whitespaces, being relevant for e.g. Markdown quotes in list elements or for code blocks. As far as I can see, I miss leading spaces in the Transifex lines at all. Maybe the files have been uploaded without these spaces or Transifex has removed them. An example file is "qrexec3.txt".
>
> 17) All the "permalink: ..." strings seem to be tagged with "notranslate" (resulting in keeping them as they are), although you agreed in your last message that those paths have to be preceeded with e.g. "/de" (German). See also 10).
>
>
>
> All in all, I suggest to restart the translation process as described in the steps below. However, waiting for a first result could also be helpful, because you could see what to improve next time.
>
>
> Step 1) Prepare a comprehensive, error-free and complete how-to documentation for translating strings. For this, visit all source text files thoroughly, at least once.
>
> Step 2) Beautify all the source text files. See https://www.qubes-os.org/doc/doc-guidelines/
>
> Step 3) Replace special characters that might vanish in Transifex (such as leading spaces) with unused strings. For the translators, it is important not to use these strings --> doc.
>
> Step 4) Cancel the current Transifex Qubes translation project and start a new one with no features like "TM Autofill".
>
> Step 5) Send the how-to-translate documentation link to the (new) translators.
>
> Step 6) Wait for glamorous translations.
>
> Step 7) Replace the strings back (reverse of step #3).
>
> Step 8) Love it!
>
>
>
> Tell me where I may help you.
>
> Kind regards,
> Tobias
>
> [1] https://help.github.com/articles/basic-writing-and-formatting-syntax/#relative-links
>
> [ Reply https://www.transifex.com/user/messages/reply/183967/ ]
>
> [1] https://www.transifex.com/user/profile/tokidev/


> 18) Other Transifex obstacles AFAIK:
> a) no empty translation string possible (means "blank lines")
> b) no untranslated strings possible (means "deleted lines")
> c) unable to insert lines
>
> 19) Other workarounds/ways for using Transifex as intended:
> a) MD -> HTML -> translate -> HTML -> MD
> b) MD -> Wiki Markup -> translate -> Wiki Markup -> MD
> c) MD -> extract texts to translate to txt (including *formattings*) -> translate -> reintegrate -> MD
>
>
> Kind regards,
> Tobias
>
> [ Reply https://www.transifex.com/user/messages/reply/183977/ ]
>
> [1] https://www.transifex.com/user/profile/tokidev/


- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQEcBAEBCAAGBQJZGtP8AAoJENuP0xzK19csIEsH+wT+TBj/jOpq2ynGRMWiha78
KLE6AMyKGX2PQGakL5VmzUwV+4QtNljkjOb+sdZoalDcGtvq4pnZScgt+fJg4P4w
0vbSkLL54sUP0Q26mT0jwyW+xenRVg5ytIB1C4pJxY04YCiwtFt4eSDfmnhw0qVK
VcUxk9USvl8lACl1kWmcV51bwkaKCcbPLHydxX2ZHyW7zTIbUbKllAKQ4E6Pmwoy
++TP01Y/L3xMdsXGWgZHiIFiQW+t3EVX2zE4lPE5T/FDyt/eZuABJvjALgE9kHSw
ZdCXyWRJf7rjDpJV6dTczg9mN3vUEQnqhPr3J+mBAg6wHKY2AiKe+muYgy/Iy0s=
=XRtd
-----END PGP SIGNATURE-----

[tokidev]

Hello everybody,

I'd like to add that yesterday, I recieved an email from Nina (the
Transifex supporter I'm currently discussing with) with a very suprising
and interesting outcome that I didn't expect:

Markdown is supported.

Even if it's not documented nor listed in the list of supported formats,
it looks very promising, at least on a screenshot she sent me. If we are
lucky then many issues I listed can be solved by just using our original
*.md files, instead of renaming them to *.txt and back again.

Could someone test it by uploading a Markdown-feature-rich *.md file to
Transifex, trying to translate it and downloading it again?

I'm going to reply Nina in about six hours and ask her about some
remaining details.

Kind regards,
Tobias

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

On 2017-05-16 05:27, Marek Marczykowski-Górecki wrote:
>> Summarizing my concerns:
>>
>> In my view, it would be very handy and helpful to provide an
>> instructions page showing the necessary rules on how to translate
>> and what to consider for gaining unbroken and well-functioning
>> Markdown files. Note that translators who don't know that these
>> phrases are parts of Markdown files could accidently break those
>> files. Also note that not everybody is well-trained in editing
>> Markdown files, knowing specials rules (like "redirect_from"
>> directives and "/paths/to/someting/", constant_filenames) and
>> anything else like that.
> This is indeed a good idea. Maybe it should be just additional
> section here: https://www.qubes-os.org/doc/doc-guidelines/ ?
>

Yes, please do feel free to submit a PR against that page.

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org
-----BEGIN PGP SIGNATURE-----

iQIcBAEBCgAGBQJZG5z+AAoJENtN07w5UDAwReUQAJVDHYum5Tfke/WQdAGaGY/k
nf7oshKay5lUtlcQAIuUCv4k0lfiMkRYaSsYMXJ9lpvN1LbVeYZhc2ROXnC3jgpY
dGCze4oHi+6Hu3gDDx8U2d2b4vGWYleOEAc1yIJabjFhoZsL6RlvC404GLpViLv4
4kWVLNA1nJ1ALc9I8FEQnPy8GQhqvf2gCXhYsXAzkNAFBgvfo+6o+rrYIeh2YJsI
/eMRnB6qsiEm55khY56pN4OpAW4hHObc6Rj7DnWB/19jwlohcM9UHN9w9fkiKxxs
Tc5Z1z9ytt5zlb28c+s+ewTWU+MIiRKLH5KGNGwmr/Lcqq/Ttqae1YTtv2ABPKoQ
/mO02KcUktTKTExvUcX2kZ8788QI/5W/2+am9h69t+fMH+RBDk25LDYWbtznSwOx
QfFjLdQlZpAysjGIkr/a2N6j4Fx7J4O9iCi58XNez86+vSIMlBzFfmLtfRF/zZDc
EDWQCW6nQNJGBMX8egDlXuxFI2wc7oM2Mu5Emh5Pf2qMFAQwd+vD3LWSC93toSZO
iguyKYdGxeHFUDcUEUZPgG6+SnWk17Q3q87BhwbhIGTnd3IPOEWQiX/h0VMmhpuP
NA5lJRu6a8oWO9Dbn4cort4NCVzWXHLiyQsTd8LBzLLlBknHneeA1uxL+1SvCtMW
6ZhNU1hsuRMlQiWikggC
=Hk1l
-----END PGP SIGNATURE-----

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

On 2017-05-16 07:22, tokidev wrote:
> Hello everybody,
>
> I'd like to add that yesterday, I recieved an email from Nina (the
> Transifex supporter I'm currently discussing with) with a very
> suprising and interesting outcome that I didn't expect:
>
> Markdown is supported.
>
> Even if it's not documented nor listed in the list of supported
> formats, it looks very promising, at least on a screenshot she
> sent me. If we are lucky then many issues I listed can be solved by
> just using our original *.md files, instead of renaming them to
> *.txt and back again.

That is, indeed, surprising, since I believe it was Nina who told us
that *.md files are not supported. This is why we were forced to
rename them to *.txt in the first place. Perhaps it's a new feature of
Transifex? If so, it's a good one!

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org
-----BEGIN PGP SIGNATURE-----

iQIcBAEBCgAGBQJZG51oAAoJENtN07w5UDAwJiAP/Rm1auHONQcnQM6ZIEvGiGk0
ZzkjkHRD/6zdd8aJ5rqqKEK/NvKFM3y6vpP52zHDfrTq7TNGZh6qS1x7Ank+NF2G
nQwOu6JH+wUB2ZI8qVzehyj7cO2h1k5ML8UCNOYnfBw66ouW8Doe35QnlReDZneU
OaGbmFwkJUS1hC3596cgkPUrZx68LNxqOH30DdmXnXDonlYuM51y5TEX8aynyJ1K
uFu2YxQ0YExSI7FWZVeRQWNeiKD8pBJc1Zwl14PVA9hu0SePeA+PrOcdJK6vdqci
C1Q8gciJMOxJAMDnVTbOhVVl8icLFaOpTDD5ix6LJgZpAyDaYYhagRCWVw4wcsTO
1Fe45cYf2SkgzFV8sbvX0hxp/XdIXBz3deppX9U/HfcaM4qFxdTi2khPJkLW4dH6
2X81VnC1/xJYPNAfNVxmnN2MgkxC0SKr4TC5A3eZHyzn01YlGJzozPzjHwrnOii8
fT+7sK6w7oMSBcXQ++/S1mO5nC5ulMPGWIJTlUqIk8qX34jXtHMU3tCt2HnKuY9Y
goHYx3fZ90GDpZPeN84DPlyPzc/Vy5Fm6JlysrfONrbDxKK1cFsPAE++ARSila+/
+L9hOkrTIZOtwnANA4fmM5asCz9gYHlQ0BjYwzmu4bWsg1m/44imo9WK+GPVlYR8
zV+jiseOOgXynjUuX139
=5tnu
-----END PGP SIGNATURE-----

[blacklight]

It might be a little off topic, but i was wondering what the requirements are to be accepted into the transifex qubes project, and in case there are noone, how long it would take to get accepted into the project?

[Michael Carbone]

Andrew David Wong:

> On 2017-05-16 07:22, tokidev wrote:
>> Hello everybody,
>
>> I'd like to add that yesterday, I recieved an email from Nina (the
>> Transifex supporter I'm currently discussing with) with a very
>> suprising and interesting outcome that I didn't expect:
>
>> Markdown is supported.
>
>> Even if it's not documented nor listed in the list of supported
>> formats, it looks very promising, at least on a screenshot she
>> sent me. If we are lucky then many issues I listed can be solved by
>> just using our original *.md files, instead of renaming them to
>> *.txt and back again.
>
> That is, indeed, surprising, since I believe it was Nina who told us
> that *.md files are not supported. This is why we were forced to
> rename them to *.txt in the first place. Perhaps it's a new feature of
> Transifex? If so, it's a good one!

also a heads-up, folks are opening a lot of issues and comments in
transifex that I don't have the capacity to answer or resolve. If anyone
with more interest/time in localization efforts can contribute that
would be really appreciated. I will also ask the Localization Lab folks.

--
Michael Carbone

Qubes OS | https://www.qubes-os.org
@QubesOS <https://www.twitter.com/QubesOS>

PGP fingerprint: D3D8 BEBF ECE8 91AC 46A7 30DE 63FC 4D26 84A7 33B4

[tokidev]

Am 17.05.2017 um 02:46 schrieb Andrew David Wong:

On 2017-05-16 07:22, tokidev wrote:
> Hello everybody,

> I'd like to add that yesterday, I recieved an email from Nina (the
>  Transifex supporter I'm currently discussing with) with a very
> suprising and interesting outcome that I didn't expect:

> Markdown is supported.

> Even if it's not documented nor listed in the list of supported
> formats, it looks very promising, at least on a screenshot she
> sent me. If we are lucky then many issues I listed can be solved by
> just using our original *.md files, instead of renaming them to
> *.txt and back again.

That is, indeed, surprising, since I believe it was Nina who told us
that *.md files are not supported. This is why we were forced to
rename them to *.txt in the first place. Perhaps it's a new feature of
Transifex? If so, it's a good one!

Hello Andrew,
hello everyone,

Here is Nina's email from a few hours ago, showing the answers to my issues, summarized here:

Issue #1: Does the feature "TM Autofill" aka "TM Fill-up" work properly without making troubles?
Issue #2: Is Markdown supported?
Issue #3: What does the tag "notranslate" mean?

Am 17.05.2017 um 11:48 schrieb Nina Eleftheriadou:

Hi Tobias,

Please find my comments/answers below:

Issue #1:

Yes, that helps. Yesterday, I tried to prove my thesis again, but it doesn't work anymore. Maybe one of the maintainers has turned that feature off? I'm a bit confused.

I'm still not sure yet, but it seems that you are right. Please pardon all the inconveniences I made.

Answer:
No. The setting is still on:



Based on the current implementation, TM is not allowed to overwrite the translations of the already translated strings.

This is the way this feature works and as far as I can tell this is the behavior that both translators and localization managers expect.

No worries. I am glad that everything is clear now.

Issue #2:
Markdown is supported?! This is indeed a very surprising and exciting outcome! Great news!

As you may read here [1], in the past, the developers of "Qubes" assumed by looking up your list of supported formats that Markdown is not supported by Transifex. That's why they decided to rename the *.md files to *.txt files first, upload those to Transifex, wait for translations, download the translated *.txt files and rename them to *.md back again. As far as I understand you now, there is no need for such a workaround. They may simply use their Markdown files directly. Is that correct?

Having said this, your list on the page [2] seems to be somewhat incomplete. (I recommend to update/complete it, since also other projects like to *see* that their formats are supported.)

Answer:
As you correctly pointed out, Markdown was not supported in the past and the TXT file format was suggested as a workaround.

However, recently we started working on the Markdown file format and a beta version will be available soon.

That's why it is not publicly available yet.

If your localization managers are interested in this format then when the beta version is available - it is expected to be deployed until the end of the current week - we can enable this for the organization as soon as we receive such a request.


Issue #3:
Concerning duplicates you said this:

> Duplicate entries within the same resource are ignored by Transifex and
> that's why they do not appear in Transifex web interface.

As far as I can see on your screen shot "Screen-Shot-2017-05-15-at-3-50-13-PM.png", the phrase "I read this book." appears twice, thus, making me happy. So, is it true that at least Markdown files are not affected by that duplicate reduction?[1]

[2]Another thing besides Markdown, concerning the tag "notranslate": What does it exactly mean? When I try to enter something different from the source phrase, a warning "Phrase tagged to receive a copy of source string as translation" appears. But what does even that mean?
a) Is it just a guideline I may break if necessary?
b) In the end, will the source phrase automatically be inserted into the translated file, regardless of the phrase in the translation box?
c) Does the translation box has to contain the source phrase, otherwise
a download won't be possible?
d) something else ...?

Answer:
Yes. Identical entries will be parsed as different strings. As a result, all of them will be available in the editor for translation[1]

[2] Localization managers can use one of the available smart tags we offer in order to prevent some strings from being translated:

• "notranslate"
• "locked".

More information about these tags can be found in our FAQ section here [Can I lock a string and prevent it from being translated?].

Please note that the administrator users of the organization has the option to set up translation checks according to which translators will get a proper error/warning message in the editor if the translation they apply is not a valid/expected one.

The translation checks that are related to the above smart tags are the following ones:



Please note that if the translation check has been set up as an error, the translation cannot be submitted.

However, if the translation check has been set up as a warning, then a warning message will appear but the translation can successfully be submitted.

More information about this functionality can be found here.

Question #1:
I would like to copy useful snippets from our conversation here and paste them into a public discussion. Is that okay for you?

Answer:
Yes, feel free to share this information with your team.

Let me know if I can be of any further assistance.

Have a nice day!

Regards,
Nina

--
Nina Eleftheriadou
Customer Success Engineer | Transifex

How would you rate my reply?

{#HS:362972210-28474#}

These are the two footnotes [1] and [2] used in the section of issue #2:

[1] https://github.com/QubesOS/qubes-issues/issues/1452
[2] https://docs.transifex.com/formats/introduction

Kind regards,
Tobias

[tokidev]

Am 17.05.2017 um 02:44 schrieb Andrew David Wong:
> On 2017-05-16 05:27, Marek Marczykowski-Górecki wrote:
>>> Summarizing my concerns:
>>>
>>> In my view, it would be very handy and helpful to provide an
>>> instructions page showing the necessary rules on how to translate
>>> and what to consider for gaining unbroken and well-functioning
>>> Markdown files. Note that translators who don't know that these
>>> phrases are parts of Markdown files could accidently break those
>>> files. Also note that not everybody is well-trained in editing
>>> Markdown files, knowing specials rules (like "redirect_from"
>>> directives and "/paths/to/someting/", constant_filenames) and
>>> anything else like that.
>> This is indeed a good idea. Maybe it should be just additional
>> section here: https://www.qubes-os.org/doc/doc-guidelines/ ?
>
>
> Yes, please do feel free to submit a PR against that page.
>
>

Hello Andrew,
hello all,

I would like to create and discuss the guidelines to follow when
translating the Qubes OS documentation.

#1
Andrew suggested to add such a section on this page [1]. I like to add
that there may be some language-dependent guidelines to work out. These
may be written on their own new page since it doesn't make sense to
translate those language-dependent guidelines.

#2
In Transifex, there is a keyboard shortcut (alt + y) to "View project's
style guide". It currently doesn't seem to work or there is no style
guide yet. Maybe, as a very short style guide, we could link to the
guidelines?

#3
In case we upload the *.md files, should we upload them next to their
*.txt pendants or should we have a clean restart? The former can help
translating, but could be confusing.

#4
I suggest that the *.md source files have to be reviewed by a native
Correct-English speaker and Markdown-beautifier before uploading them to
Transifex.

#5
I suggest to either open a new "qubes-translation" mailing list [2] or
at least to add an invitation for translators to join the "qubes-devel"
list here [3].
Please check if the translation guidelines page looks like intended.

#6
Instead of creating a GitHub account and requesting to pull, there is a
nice attachment in this email here, containing my quick-and-dirty
proposal for the "Translation Guidelines". For getting a preview, I used
a Markdown parser that is probably different from that one used on
www.qubes-os.org. Thus, you have to adapt where necessary. Note that
these guidelines imply a certain workflow that also has to be worked out
yet. Feel free to discuss, correct and adapt.


Kind regards,
Tobias


[1] https://www.qubes-os.org/doc/doc-guidelines/
[2] https://www.qubes-os.org/mailing-lists/
[3] https://www.qubes-os.org/mailing-lists/#qubes-devel

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Hi Tobias,

Thank you for sharing your thoughts on this. I'm afraid everyone on
the Qubes team is extremely busy with other projects and tasks right
now, so we probably won't be able to comment or act on this for quite
a while, especially since this is a rather long email and attachment.

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org
-----BEGIN PGP SIGNATURE-----

iQIcBAEBCgAGBQJZINk0AAoJENtN07w5UDAwEAwP/i+4f/HlHm8+ESese5935UbL
iAm0QtvMkYTd9BdOzLcm4ZwLXNQpLZRNe2StLd14acOq7w6j9nxZpWb5E9Tcpa+j
ZltLPIzli/SOqMBAmZnqMM8S34jbEFgRUa8V///3Je6DL7VP5sIhZ757c7q422Rq
KeAVCLf99PkKc9PjkFYQ+/if32ET/3pA7mBf8DL161b1/NSnbHtCPWyHbDiGc+Q9
lj9N7DoQq+ndCP6zMaTkCqt//9Y2IzbTAZ3v3dbn4ky9PfCw/3graTkbcaFZd4vD
JNzfhU0iOiJ9K9hPM0yLCU8I0MzVmas4ORCrmUrSBSz74XLMxmlihBz6TvKwIRjO
6KjLgFO9I3SpwANsYH0aqNXiuggUsKO0bKVJDnbEUUm7EZI7XhnFdKlp4zpnDygj
77zN+RIQpvjNGdyMCf9I93jDFk6HMVqm4qKFSnxz5jituQSPXBML1MnfmF5oYKZ/
pNnkQ+5vmBJCMBvaH2LwWbTWFG2xho2CPcEjKAK1PuMR/WPmlavlz25yVJ4sNYar
dC+3gK1M4qJ7gMsXLY/AVdgUAgLR3MHFNOdUAykQGibB6R3tjyLTstQ1Odyfa5NU
jr56ocoxukoKJxvwtbi1pm1GixUlpazUeVKiUBtdVtKFlQUDbuhgfz6GA3zeuBBk
beU0mtHFIgB26kVaxNTn
=bc6c
-----END PGP SIGNATURE-----

[tokidev]

Thank you to inform us about the circumstances. Please pardon my long email.

I don't know if other translators will have enough time to help but
would it be possible for some of us to undertake the "translation
project" job? It looks like you need more manpower.

Tobias

[blacklight]

I would happily volunteer if needed, I am a dutch translator.

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

I think that should be possible.

> It looks like you need more manpower.

Yes.

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org
-----BEGIN PGP SIGNATURE-----

iQIcBAEBCgAGBQJZId+UAAoJENtN07w5UDAw1xsP/i+4ASKywdPI1xZ2W6KOReW8
tzG9bCBbsIc9DQLao/20sRCjeequnLVk+qxl1JGo/kUWb7xULz5k76AvGp7HqS/m
hwUKAEyNvhxdgcQBxA91SWqvqaJ44KtORddPExDvqDuPOHGMdEbjvLaGMW+qzEGp
UcKo0Oxfj1RRgn5Bqd/HoBynLDeAXRLn0KWVucs3xkehtVSiAyvdghNpNSbD9EuM
3ZMd8Pn0QYr4psmsDnrYWRQ6dwnztVHh/3lSeW/pmnRUosArhwre3w1RBd2k+Mk0
r4RzkfW8xgw6MnskD4rYhVEp8V0931mKKLR8tV6/jog6E78+OnbkBd7ZDmjTXuoM
2zcEeV1mAYGQ2c00JNlnFhe/IGHXgLEdUzXwG4u3AuJq5BFNLky7C+3JE/dbUGwL
8HV42Yy0O+GL0DazriVsVZtqbsSD0KWoCSuu6JiEWf+Pz73EnQW2KxAaMJyc2eQv
sjBounumnZZ2egMXJMA74BIv4uQN+hznV3VQdLSvOnKsRW2MA4j+adu7bU57Fhu2
u5O2QTnbNwPEONOhHzqQTgADtUHLB0xgZbbWeBoHOgLd9NEmwCGNSCbcv0/bwr85
bBAIXgG1CsqdGYALRPetuZ7vMbxtXVUcU7hTiiPhc9LHFrdL/Ho20sSEw9hFHr5k
BGxD8cjhTnZSRFek/seX
=xAuI
-----END PGP SIGNATURE-----

[blacklight]

Where could we start with such a project, maybe the qubes issues page om github?

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

On 2017-05-21 13:55, blacklight wrote:
> Where could we start with such a project, maybe the qubes issues
> page om github?
>

Yes, here's an issue for it:

https://github.com/QubesOS/qubes-issues/issues/2824

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org
-----BEGIN PGP SIGNATURE-----

iQIcBAEBCgAGBQJZIgN6AAoJENtN07w5UDAwcqEP/3vMXCCKoQtr/N29DZOQhHMx
BbSdXKLegVnRw/Bfbajjchlm30f2E2230gwRd9DNBDctvlN+99hx2OVpnRuZXm6O
Nr+2HuZEcMjMYymg8mdP05cXjPEtY8sY/qpKBHXILk0v/J/vW9COD7536dcD1jtU
fbJpHNvPRUWwisrnPOwjOTA2PeDqke8is9vEjbEM+Y6rutLIaK7Rmk8RneAo9Td1
FxoOLCzXDrsU9ELm53ruCaZUTNmZU3ZMtrh4x8U0xxD/GKb2B6CjBOgGD0KJtnkX
Ziaakkf82B7IBNU1GegrHW5lrAP2kqAed4FQabkuqQ1kQmu5/q/OU3D6m7d/TK6t
L+MJUvOMyg75dvqQQqY/ECbZuIt0Y71KyDQKg6uTdEjwqNUHVA4u8YU8fGzYkII1
ijumnpch3kJE6X6iLUrEP/fvNfsQv2YExuiyS+Vad1YNlnQ31Acf3cNSg7xOudBN
daJZzl0Q11kqMvdCVvb70+0PPDTM+tMJUQ781WTHcUo9l36P60H7o9gOfbqELrGP
0N2pcIrpFjClWf08Nk60C9SDdMs9eh9L6aUbZjpmR1/w6N4+VadRU/IHZalI/uCA
CtiIWlHUXaR+8Zeb8Hq1ich+WCse8RPU5Gseywhq0qhScH5+2i7dzCvIZKzUpi3T
jlJlnexXKC4hUhSoupzq
=AGCT
-----END PGP SIGNATURE-----

[tokidev]

Am 17.05.2017 um 16:31 schrieb Michael Carbone:
> also a heads-up, folks are opening a lot of issues and comments in
> transifex that I don't have the capacity to answer or resolve. If anyone
> with more interest/time in localization efforts can contribute that
> would be really appreciated. I will also ask the Localization Lab folks.
>

Hello Michael,

I'm interested in helping you. Since there could be others who like to
help, too, I share this conversation with the mailing list.

I have some questions regarding autonomy:

1) How much power do you want to give me (and others) and how can I (we)
recognize if an action lies within that power?

2) Which issues and comments do you mean? How can I (we) access them?

3) Do I (we) have to report the progress? And/or the solutions? And how
frequently?

Kind regards,
Tobias

[Michael Carbone]

tokidev:

> Am 17.05.2017 um 16:31 schrieb Michael Carbone:
>> also a heads-up, folks are opening a lot of issues and comments in
>> transifex that I don't have the capacity to answer or resolve. If anyone
>> with more interest/time in localization efforts can contribute that
>> would be really appreciated. I will also ask the Localization Lab folks.
>>
>
> Hello Michael,
>
> I'm interested in helping you. Since there could be others who like to
> help, too, I share this conversation with the mailing list.
>
> I have some questions regarding autonomy:
>
> 1) How much power do you want to give me (and others) and how can I (we)
> recognize if an action lies within that power?

At minimum anyone can apply to be a translator for the project on
transifex. If you want to do additional efforts (as you have been
doing), we can make you a coordinator, which would allow you to create
discussions, resolve translation issues within transifex.

Andrew/Marek we okay with that?

I've asked Erin at Localization Lab (cc'ed) what that process is to do
so, because our set-up in Transifex makes it non-obvious to me.

> 2) Which issues and comments do you mean? How can I (we) access them?

I think you need to be a coordinator or maintainer to receive the
notifications (or "watch" the project?), things like:

https://www.transifex.com/otf/qubes/translate/#es/development-workflowtxt/66425501
https://www.transifex.com/otf/qubes/translate/#es/development-workflowtxt/66425509
https://www.transifex.com/otf/qubes/translate/#es/development-workflowtxt/66425545
https://www.transifex.com/otf/qubes/translate/#es/development-workflowtxt/66425548
https://www.transifex.com/otf/qubes/translate/#es/development-workflowtxt/66425546
https://www.transifex.com/otf/qubes/translate/#es/development-workflowtxt/66425542
https://www.transifex.com/otf/qubes/translate/#es/development-workflowtxt/66425557

and further ago:

https://www.transifex.com/otf/qubes/translate/#fr/glossarytxt/109041574
https://www.transifex.com/otf/qubes/translate/#fr/glossarytxt/109041573
https://www.transifex.com/otf/qubes/translate/#es/glossarytxt/109041564
https://www.transifex.com/otf/qubes/translate/#es/qubes_manager/107414540
https://www.transifex.com/otf/qubes/translate/#es/glossarytxt/109041573
https://www.transifex.com/otf/qubes/translate/#es/qubes_manager/107414567
https://www.transifex.com/otf/qubes/translate/#fr/glossarytxt/109041538

some of these efforts involve fixing issues found in the english during
the translation process back in the qubes-doc and qubesos.github.io repos.

> 3) Do I (we) have to report the progress? And/or the solutions? And how
> frequently?

I would love to know other folks' thoughts on what the ideal workflow
would be. We want some way to know when a resource has been fully
translated, so that it can be reviewed and then included in builds.

If you run into any issues or have questions, please post them on
qubes-devel -- also Erin from Localization Lab has a lot of experience
and knowledge regarding the Transifex platform and localization
community, which may be helpful in your efforts as well.

They have a dedicated mailing list for managing localization/translation
efforts:

https://groups.google.com/forum/#!forum/otfl10n
more info: https://www.localizationlab.org/

If the traffic becomes too much maybe we'll create a
localization/internationalization mailing list dedicated to this.

Michael

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

On 2017-05-25 07:52, Michael Carbone wrote:
> tokidev:
>> Am 17.05.2017 um 16:31 schrieb Michael Carbone:
>>> also a heads-up, folks are opening a lot of issues and comments in
>>> transifex that I don't have the capacity to answer or resolve. If anyone
>>> with more interest/time in localization efforts can contribute that
>>> would be really appreciated. I will also ask the Localization Lab folks.
>>>

>> I'm interested in helping you. Since there could be others who like to
>> help, too, I share this conversation with the mailing list.
>>
>> I have some questions regarding autonomy:
>>
>> 1) How much power do you want to give me (and others) and how can I (we)
>> recognize if an action lies within that power?
>
> At minimum anyone can apply to be a translator for the project on
> transifex. If you want to do additional efforts (as you have been
> doing), we can make you a coordinator, which would allow you to create
> discussions, resolve translation issues within transifex.
>
> Andrew/Marek we okay with that?
>

Yes. :)

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org
-----BEGIN PGP SIGNATURE-----

iQIcBAEBCgAGBQJZJ6PNAAoJENtN07w5UDAwHsoQAM2rpE7hEr2QRbuUShFdSqT1
ICP8U/4YR8dHVcmbkiS6UbjwFp3o7gAgHy+WzTYEryeCp7rmuqQ+RZIoyDNmtQbG
LZ7QeiQQS7fsjnYIDF4eLk5fqZr4GzOMGx/+TZrM8MjicgCu96rF4PExw1CvDUgB
2Hq3IAf3YESHNeGx6CsnBU/dm38SF1pI+sXUUYBOpGgsq3pDuABLvy1NNgzandsi
dtQicuV719Ia4w7v2TNi3SEOHpvDnh3gOAu+DmoxyG8LGpR+Bqnri7EcTBAoL40M
zrDORV/41QrUObvUukXp/uiKHPr0893TLw7iVVwg1UzhbZE/fnf9iJcnQfNaJhW3
D+0RNHhTJoJDZrgHEgkBZ9t+fNCxFHYY2/w8BRb9XmiT37UuNgSmtx3YQbJwTRF0
HtufMqtB6UuvL9g7fVnYk8YkLj/+mQFYYMgRT8AYXLOnMQ51l0Xtl391Az5QPCkx
Ywf4r+3TpwCTHF5GbBzS7GB03tsYiJy3auO8zyIsRghCr9sMuu/aR7TAun70Hxb/
2ndfLSpJE3giz0j/4jw5KOpZLy02JDqspvzK1EI4ume9IyVzsGPOWWPvUy8uB3bl
dRN6ZKJgAtJ3OLE27Qb497QYbB3QgoDYkUHdHWLPLIbQFvC/1pYPm6sjp4eXm/o0
E5OomJp3rS1+3oiWzi/a
=wwZf
-----END PGP SIGNATURE-----

[tokidev]

Am 25.05.2017 um 14:52 schrieb Michael Carbone:
> tokidev:
>> Am 17.05.2017 um 16:31 schrieb Michael Carbone:
>>> also a heads-up, folks are opening a lot of issues and comments in
>>> transifex that I don't have the capacity to answer or resolve. If anyone
>>> with more interest/time in localization efforts can contribute that
>>> would be really appreciated. I will also ask the Localization Lab folks.
>>>
>>
>> Hello Michael,
>>
>> I'm interested in helping you. Since there could be others who like to
>> help, too, I share this conversation with the mailing list.
>>
>> I have some questions regarding autonomy:
>>
>> 1) How much power do you want to give me (and others) and how can I (we)
>> recognize if an action lies within that power?
>
> At minimum anyone can apply to be a translator for the project on
> transifex. If you want to do additional efforts (as you have been
> doing), we can make you a coordinator, which would allow you to create
> discussions, resolve translation issues within transifex.

I appreciate the idea of becoming a coordinator. But first, I like to
know/model the whole translation process/workflow since it doesn't make
sense for me to coordinate without knowing that process in detail.

>
> Andrew/Marek we okay with that?
>
> I've asked Erin at Localization Lab (cc'ed) what that process is to do
> so, because our set-up in Transifex makes it non-obvious to me.
>
>> 2) Which issues and comments do you mean? How can I (we) access them?
>
> I think you need to be a coordinator or maintainer to receive the
> notifications (or "watch" the project?), things like:
>
> https://www.transifex.com/otf/qubes/translate/#es/development-workflowtxt/66425501
> https://www.transifex.com/otf/qubes/translate/#es/development-workflowtxt/66425509
> https://www.transifex.com/otf/qubes/translate/#es/development-workflowtxt/66425545
> https://www.transifex.com/otf/qubes/translate/#es/development-workflowtxt/66425548
> https://www.transifex.com/otf/qubes/translate/#es/development-workflowtxt/66425546
> https://www.transifex.com/otf/qubes/translate/#es/development-workflowtxt/66425542
> https://www.transifex.com/otf/qubes/translate/#es/development-workflowtxt/66425557
>
> and further ago:
>
> https://www.transifex.com/otf/qubes/translate/#fr/glossarytxt/109041574
> https://www.transifex.com/otf/qubes/translate/#fr/glossarytxt/109041573
> https://www.transifex.com/otf/qubes/translate/#es/glossarytxt/109041564
> https://www.transifex.com/otf/qubes/translate/#es/qubes_manager/107414540
> https://www.transifex.com/otf/qubes/translate/#es/glossarytxt/109041573
> https://www.transifex.com/otf/qubes/translate/#es/qubes_manager/107414567
> https://www.transifex.com/otf/qubes/translate/#fr/glossarytxt/109041538
>

I can't access any of these pages (I get a server error message). But if
you mean the discussions in the lower right corner of the translation
page, I have a rough idea of it.

> some of these efforts involve fixing issues found in the english during
> the translation process back in the qubes-doc and qubesos.github.io repos.

I see. Could be done with PRs.

>
>> 3) Do I (we) have to report the progress? And/or the solutions? And how
>> frequently?
>
> I would love to know other folks' thoughts on what the ideal workflow
> would be. We want some way to know when a resource has been fully
> translated, so that it can be reviewed and then included in builds.

I fully agree with you.

>
> If you run into any issues or have questions, please post them on
> qubes-devel -- also Erin from Localization Lab has a lot of experience
> and knowledge regarding the Transifex platform and localization
> community, which may be helpful in your efforts as well.

Okay.

>
> They have a dedicated mailing list for managing localization/translation
> efforts:
>
> https://groups.google.com/forum/#!forum/otfl10n

I can't access it without a Google account. I won't register one, so,
I'm sorry.

> more info: https://www.localizationlab.org/
>
> If the traffic becomes too much maybe we'll create a
> localization/internationalization mailing list dedicated to this.

I agree with that since localization/internationalization might be
uninteresting for many qubes-devel followers and vice versa.

>
> Michael
>

Kind regards,
Tobias