Translation Guidelines

[andrewdavidwong]

• Guidelines proposed by Tobias
• Full discussion thread

It would be great if members of the community could take the initiative on this project.

[blacklight447]

I think that i'll be able to help with this. where should such a page be uploaded though? someone on the doc pagehere at github?

[blacklight447]

I think that i'll be able to help with this. where should such a page be uploaded though? someone on the doc pagehere at github?

[andrewdavidwong]

Yes. It could be modeled after the Documentation Guidelines:

https://www.qubes-os.org/doc/doc-guidelines/

[andrewdavidwong]

Yes. It could be modeled after the Documentation Guidelines:

https://www.qubes-os.org/doc/doc-guidelines/

[tokideveloper]

Hello guys!
Now that I have a GitHub account, I'm ready to discuss my proposed guidelines here.
Tobias

[tokideveloper]

Hello guys!
Now that I have a GitHub account, I'm ready to discuss my proposed guidelines here.
Tobias

[tokideveloper]

@andrewdavidwong @blacklight447
See here for a translation workflow prosposal. Feel free to comment it here.

[tokideveloper]

@andrewdavidwong @blacklight447
See here for a translation workflow prosposal. Feel free to comment it here.

[blacklight447]

looks good, but how are we going to implement something like this.
We also have to figure out how people can apply for one of these roles, do they need to be a known member of the community? Where can they apply and who will be responsible for this?
We could potentially create a mailing list where these things can be discussed. It could also be an appropriate place where people could apply for one of these roles.
By doing this, we create the oppertunity to talk with the volunteers, and previously solved issue's will also be searchable for new volunteers in the future.

@andrewdavidwong Do you think it is possible to create a new mailing list for this?
@tokideveloper I would also like your thoughts on this.

[blacklight447]

looks good, but how are we going to implement something like this.
We also have to figure out how people can apply for one of these roles, do they need to be a known member of the community? Where can they apply and who will be responsible for this?
We could potentially create a mailing list where these things can be discussed. It could also be an appropriate place where people could apply for one of these roles.
By doing this, we create the oppertunity to talk with the volunteers, and previously solved issue's will also be searchable for new volunteers in the future.

@andrewdavidwong Do you think it is possible to create a new mailing list for this?
@tokideveloper I would also like your thoughts on this.

[tokideveloper]

@blacklight447:

looks good,

Thank you!

but how are we going to implement something like this.

What do you mean by "something"? Everything?

I could write step-by-step instructions where necessary, but I like to know what's unclear in advance.

We also have to figure out how people can apply for one of these roles, do they need to be a known member of the community? Where can they apply and who will be responsible for this?

In my view, everybody who likes to possess one or more of these roles is welcome. As long as they do their jobs, it's sufficient. AFAIK, the commits of the translated versions won't be signed, thus, quality, responsibility etc. are up to the volunteers.

In my proposal, I wrote that anybody who likes to get a role may write to a dedicated mailing list to apply for that role. Now, I suggest that the controller shall be the responsible one for such applications instead. But as long as there is no controller, the dedicated mailing list might be always the fallback way. (But I prefer to write to the controller only due to "mailing list noise reduction".)

We could potentially create a mailing list where these things can be discussed.

I prefer to create a mailing list. Let's call it qubes-translation as already mentioned in my proposal (or any other name you like).

It could also be an appropriate place where people could apply for one of these roles.

See above.

By doing this, we create the oppertunity to talk with the volunteers, and previously solved issue's will also be searchable for new volunteers in the future.

Nice idea! But I suggest to manifest the solutions into the "Translation workflow" directly (with an optional link to the discussion).

See also the issues #1333, #1452 and #2652 for more discussions (both in general and in special).

[tokideveloper]

@blacklight447:

looks good,

Thank you!

but how are we going to implement something like this.

What do you mean by "something"? Everything?

I could write step-by-step instructions where necessary, but I like to know what's unclear in advance.

We also have to figure out how people can apply for one of these roles, do they need to be a known member of the community? Where can they apply and who will be responsible for this?

In my view, everybody who likes to possess one or more of these roles is welcome. As long as they do their jobs, it's sufficient. AFAIK, the commits of the translated versions won't be signed, thus, quality, responsibility etc. are up to the volunteers.

In my proposal, I wrote that anybody who likes to get a role may write to a dedicated mailing list to apply for that role. Now, I suggest that the controller shall be the responsible one for such applications instead. But as long as there is no controller, the dedicated mailing list might be always the fallback way. (But I prefer to write to the controller only due to "mailing list noise reduction".)

We could potentially create a mailing list where these things can be discussed.

I prefer to create a mailing list. Let's call it qubes-translation as already mentioned in my proposal (or any other name you like).

It could also be an appropriate place where people could apply for one of these roles.

See above.

By doing this, we create the oppertunity to talk with the volunteers, and previously solved issue's will also be searchable for new volunteers in the future.

Nice idea! But I suggest to manifest the solutions into the "Translation workflow" directly (with an optional link to the discussion).

See also the issues #1333, #1452 and #2652 for more discussions (both in general and in special).

[blacklight447]

Do you mean modifying this to include the idea of having a mailing list?

[blacklight447]

Do you mean modifying this to include the idea of having a mailing list?

[jpouellet]

@tokideveloper not sure the best place to leave comments on your proposal, so I'll just leave them here:

The Lister

The lister has to update the ranking list of the most urgent webpages to translate. To do so, he/she has to keep in mind:

• As a rule of thumb: Higher visitor access rate means higher priority.

We don't have that information. See: #2711

The Beautifier

I'm not sure it makes sense to have a dedicated role for this. Everybody is of course welcome to suggest any improvements to the canonical documentation as their time allows.

The Uploader

It seems to me that this role could be entirely automated, and therefore should be. See #1452

The Reviewer

(For languages where we have enough people wishing to contribute)

Might be worth explicitly stating that they are of course welcome and encouraged to help, suggest improvements, and should necessarily point out things they believe to be incorrect.

The Downloader

IMO should be automated, same as Uploader.

The Tester

Reviewing is not enough since links should be checked for plausible working and naming and even reviewers can make mistakes. Thus, a tester should [...]

The parts which don't overlap with the responsibility of the Reviewer seem to be fairly good targets for automation as well.

[jpouellet]

@tokideveloper not sure the best place to leave comments on your proposal, so I'll just leave them here:

The Lister

The lister has to update the ranking list of the most urgent webpages to translate. To do so, he/she has to keep in mind:

• As a rule of thumb: Higher visitor access rate means higher priority.

We don't have that information. See: #2711

The Beautifier

I'm not sure it makes sense to have a dedicated role for this. Everybody is of course welcome to suggest any improvements to the canonical documentation as their time allows.

The Uploader

It seems to me that this role could be entirely automated, and therefore should be. See #1452

The Reviewer

(For languages where we have enough people wishing to contribute)

Might be worth explicitly stating that they are of course welcome and encouraged to help, suggest improvements, and should necessarily point out things they believe to be incorrect.

The Downloader

IMO should be automated, same as Uploader.

The Tester

Reviewing is not enough since links should be checked for plausible working and naming and even reviewers can make mistakes. Thus, a tester should [...]

The parts which don't overlap with the responsibility of the Reviewer seem to be fairly good targets for automation as well.

[blacklight447]

How would you automate these roles like this? are you proposing something like a script?
also, we might be able to combine the role of the uploader and downloader.

[blacklight447]

How would you automate these roles like this? are you proposing something like a script?
also, we might be able to combine the role of the uploader and downloader.

[tokideveloper]

@blacklight447 from here:

Do you mean modifying this to include the idea of having a mailing list?

I don't know what you mean (or my English is bad). Maybe it's better to cite my sentence/phrase you refer to.

[tokideveloper]

@blacklight447 from here:

Do you mean modifying this to include the idea of having a mailing list?

I don't know what you mean (or my English is bad). Maybe it's better to cite my sentence/phrase you refer to.

[tokideveloper]

@jpouellet from here:

not sure the best place to leave comments on your proposal, so I'll just leave them here:

It's totally okay to leave them here, since that is the way I wanted.

The Lister

The lister has to update the ranking list of the most urgent webpages to translate. To do so, he/she has to keep in mind:

    As a rule of thumb: Higher visitor access rate means higher priority.

We don't have that information. See: #2711

I see. So, I suggest not to remove that point but to add your hint like this:

    As a rule of thumb: Higher visitor access rate means higher priority. *Currently, we don't have that information (see #2711). So you need to guess.*

The Beautifier

I'm not sure it makes sense to have a dedicated role for this. Everybody is of course welcome to suggest any improvements to the canonical documentation as their time allows.

Okay, actually I've mixed two different subroles here: (1) Preparing for translating at Transifex and (2) beautifying other details.

Subrole (1) is the important one that has to take care for this:

• Each sentence shall not need multiple lines and each line shall not have multiple sentences. This makes translation things much easier and leads to a cleaner solution. See also the 2nd point at the Markdown Conventions.
• Links have to work properly.
• The column Beautified in the Translation Priority List has to be updated (set to "yes" where beautified).

Subrole (2) is, in my view, less important than the first one, but somewhat more than just improving the canonical documentation. The thing is that I've seen many correction proposals (for the canonical version) as comments or issues via the Transifex interface. Thus, it seems to be easier for translators and reviewers at Transifex to propose corrections there than copying/forking/editing/pull-requesting the docs. This is where the "Beautifier, subrole (2)" comes: Watch these suggestions and copy/fork/edit/pull-request the docs.

If you like we could split the "Beautifier" role into let's say the "Preparer" (subrole (1)) and the "Correction Helper" (subrole (2)).

By the way: I'd like to see subrole (1) fully automated, but I'm not sure if this would always work correctly. I know that there is a handy tool as pointed out by andrewdavidwong here:

As for fixing the actual line breaks, my dear friend @gsganden developed this handy tool: https://github.com/gsganden/sentence-separator

Perhaps it would be useful here.

... but it seems that it can only be used with caution.

The Uploader

It seems to me that this role could be entirely automated, and therefore should be. See #1452

I've not seen yet that automating this role really works. On the issue you referred to, almost everything looks like having been done by hand. Maybe you are right, but I haven't seen it yet.

Please keep also in mind that my proposed workflow pays a lot attention to the "Translation Priority List" where (beside sorting by priority) each file can be tracked (important for marking translations as outdated or something like that). Thus, an automation has to update that table, too (and parsing it might be difficult).

However, I also like automations.

The Reviewer

(For languages where we have enough people wishing to contribute)

Might be worth explicitly stating that they are of course welcome and encouraged to help, suggest improvements, and should necessarily point out things they believe to be incorrect.

I can add this to my proposal.

But I'm not sure if you mean to help improving the canonical version or the translated ones. The latter is especially for reviewers (of course), the former is -in my view- for everyone.

The Downloader

IMO should be automated, same as Uploader.

See above.

The Tester

Reviewing is not enough since links should be checked for plausible working and naming and even reviewers can make mistakes. Thus, a tester should [...]

The parts which don't overlap with the responsibility of the Reviewer seem to be fairly good targets for automation as well.

Yes, if there is any. (It doesn't look so.)
Note that even Transifex could make mistakes (especially with Markdown, which is currently BETA). I don't know if an automation could check this.

Don't get me wrong. I like automation, too, but I'm afraid that it could fail and produce undetected errors. That's why I have introduced these many roles with their responsible and sometimes extensive jobs.

Thank you for your comments!

[tokideveloper]

@jpouellet from here:

not sure the best place to leave comments on your proposal, so I'll just leave them here:

It's totally okay to leave them here, since that is the way I wanted.

The Lister

The lister has to update the ranking list of the most urgent webpages to translate. To do so, he/she has to keep in mind:

    As a rule of thumb: Higher visitor access rate means higher priority.

We don't have that information. See: #2711

I see. So, I suggest not to remove that point but to add your hint like this:

    As a rule of thumb: Higher visitor access rate means higher priority. *Currently, we don't have that information (see #2711). So you need to guess.*

The Beautifier

I'm not sure it makes sense to have a dedicated role for this. Everybody is of course welcome to suggest any improvements to the canonical documentation as their time allows.

Okay, actually I've mixed two different subroles here: (1) Preparing for translating at Transifex and (2) beautifying other details.

Subrole (1) is the important one that has to take care for this:

• Each sentence shall not need multiple lines and each line shall not have multiple sentences. This makes translation things much easier and leads to a cleaner solution. See also the 2nd point at the Markdown Conventions.
• Links have to work properly.
• The column Beautified in the Translation Priority List has to be updated (set to "yes" where beautified).

Subrole (2) is, in my view, less important than the first one, but somewhat more than just improving the canonical documentation. The thing is that I've seen many correction proposals (for the canonical version) as comments or issues via the Transifex interface. Thus, it seems to be easier for translators and reviewers at Transifex to propose corrections there than copying/forking/editing/pull-requesting the docs. This is where the "Beautifier, subrole (2)" comes: Watch these suggestions and copy/fork/edit/pull-request the docs.

If you like we could split the "Beautifier" role into let's say the "Preparer" (subrole (1)) and the "Correction Helper" (subrole (2)).

By the way: I'd like to see subrole (1) fully automated, but I'm not sure if this would always work correctly. I know that there is a handy tool as pointed out by andrewdavidwong here:

As for fixing the actual line breaks, my dear friend @gsganden developed this handy tool: https://github.com/gsganden/sentence-separator

Perhaps it would be useful here.

... but it seems that it can only be used with caution.

The Uploader

It seems to me that this role could be entirely automated, and therefore should be. See #1452

I've not seen yet that automating this role really works. On the issue you referred to, almost everything looks like having been done by hand. Maybe you are right, but I haven't seen it yet.

Please keep also in mind that my proposed workflow pays a lot attention to the "Translation Priority List" where (beside sorting by priority) each file can be tracked (important for marking translations as outdated or something like that). Thus, an automation has to update that table, too (and parsing it might be difficult).

However, I also like automations.

The Reviewer

(For languages where we have enough people wishing to contribute)

Might be worth explicitly stating that they are of course welcome and encouraged to help, suggest improvements, and should necessarily point out things they believe to be incorrect.

I can add this to my proposal.

But I'm not sure if you mean to help improving the canonical version or the translated ones. The latter is especially for reviewers (of course), the former is -in my view- for everyone.

The Downloader

IMO should be automated, same as Uploader.

See above.

The Tester

Reviewing is not enough since links should be checked for plausible working and naming and even reviewers can make mistakes. Thus, a tester should [...]

The parts which don't overlap with the responsibility of the Reviewer seem to be fairly good targets for automation as well.

Yes, if there is any. (It doesn't look so.)
Note that even Transifex could make mistakes (especially with Markdown, which is currently BETA). I don't know if an automation could check this.

Don't get me wrong. I like automation, too, but I'm afraid that it could fail and produce undetected errors. That's why I have introduced these many roles with their responsible and sometimes extensive jobs.

Thank you for your comments!

[andrewdavidwong]

@tokideveloper and @blacklight447:

Thank you both for your work on this so far. We've created a new mailing list, as requested:

https://groups.google.com/forum/#!forum/qubes-translation

We think it would be best for you both to share the lead role in this. You should discuss your decisions together and be open to input from the community. Once you've arrived at a consensus (between the two of you) on any given decision, you should proceed to act on that decision and accept responsibility for the outcome (without seeking further approval from the Qubes team, unless it's something truly major). This includes things like the Translation Guidelines and Workflow.

[andrewdavidwong]

@tokideveloper and @blacklight447:

Thank you both for your work on this so far. We've created a new mailing list, as requested:

https://groups.google.com/forum/#!forum/qubes-translation

We think it would be best for you both to share the lead role in this. You should discuss your decisions together and be open to input from the community. Once you've arrived at a consensus (between the two of you) on any given decision, you should proceed to act on that decision and accept responsibility for the outcome (without seeking further approval from the Qubes team, unless it's something truly major). This includes things like the Translation Guidelines and Workflow.

[tokideveloper]

Thank you, @andrewdavidwong, I feel very honored. It's really a major honor for me to have a lead role and I'm very pleased about that. I'll give my best, together with blacklight447, to make Qubes OS eventually multilingual.

[tokideveloper]

Thank you, @andrewdavidwong, I feel very honored. It's really a major honor for me to have a lead role and I'm very pleased about that. I'll give my best, together with blacklight447, to make Qubes OS eventually multilingual.

[blacklight447]

Im glad to hear that things are starting get get momentum, im very excited about the future developments.
Also, @tokideveloper do you have a instant messaging client I can reach you with? Because discussing things might be easier when its in real time, it makes brainstorming together alot easier.

[blacklight447]

Im glad to hear that things are starting get get momentum, im very excited about the future developments.
Also, @tokideveloper do you have a instant messaging client I can reach you with? Because discussing things might be easier when its in real time, it makes brainstorming together alot easier.

[tokideveloper]

From @blacklight447:

Also, @tokideveloper do you have a instant messaging client I can reach you with? Because discussing things might be easier when its in real time, it makes brainstorming together alot easier.

It's indeed a great idea! I haven't thought about it yet, since emails are more "tangible" than IM messages.

In addition, I think it's important to have discussions publicly and logged, because other people now and in the future might be well interested in today's discussions. Thus, the new qubes-translation mailing list might be a nice way to find common ground with everyone.

Nontheless, we can brainstorm via IM as you like, but we should summarize the result, its pros and cons and post it on qubes-translation for further discussions and transparency.

(Now, as I think further, it might be good if we could create an IRC channel open for the whole Qubes translation community. But as long as there is no really need for it, I wouldn't set up one.)

See my email (coming soon) for discussions on which IM protocol to use.

[tokideveloper]

From @blacklight447:

Also, @tokideveloper do you have a instant messaging client I can reach you with? Because discussing things might be easier when its in real time, it makes brainstorming together alot easier.

It's indeed a great idea! I haven't thought about it yet, since emails are more "tangible" than IM messages.

In addition, I think it's important to have discussions publicly and logged, because other people now and in the future might be well interested in today's discussions. Thus, the new qubes-translation mailing list might be a nice way to find common ground with everyone.

Nontheless, we can brainstorm via IM as you like, but we should summarize the result, its pros and cons and post it on qubes-translation for further discussions and transparency.

(Now, as I think further, it might be good if we could create an IRC channel open for the whole Qubes translation community. But as long as there is no really need for it, I wouldn't set up one.)

See my email (coming soon) for discussions on which IM protocol to use.

[jpouellet]

In addition, I think it's important to have discussions publicly and *logged, because other people now and in the future might be well interested in today's discussions. Thus, the new qubes-translation mailing list might be a nice way to find common ground with everyone.

👍 +1 +10000 I can't agree more. I've personally found the qubes-devel and qubes-users and github ticket archives to be immensely informative, and they are a fantastic reference. I'd imagine others may feel the same about qubes-translation (if and only if the discussions actually take place on it).

[jpouellet]

In addition, I think it's important to have discussions publicly and *logged, because other people now and in the future might be well interested in today's discussions. Thus, the new qubes-translation mailing list might be a nice way to find common ground with everyone.

👍 +1 +10000 I can't agree more. I've personally found the qubes-devel and qubes-users and github ticket archives to be immensely informative, and they are a fantastic reference. I'd imagine others may feel the same about qubes-translation (if and only if the discussions actually take place on it).

[blacklight447]

I ofcourse want everything to be open, but I mean to first brainstorm together, and then posting the results to the mailing list. giving a summary of the results, why we made certain choices for example, and continuing the discussion there with the rest of the community, so they can make comments and give more idea input. another idea would indeed to have some sort of open discussion channel where community members can join in anytime with us like IRC (like @tokideveloper said).

[blacklight447]

I ofcourse want everything to be open, but I mean to first brainstorm together, and then posting the results to the mailing list. giving a summary of the results, why we made certain choices for example, and continuing the discussion there with the rest of the community, so they can make comments and give more idea input. another idea would indeed to have some sort of open discussion channel where community members can join in anytime with us like IRC (like @tokideveloper said).

[tokideveloper]

I agree with blacklight447. The idea of we two using IM is to make quick proposals for the community, not quick decisions against the community.

[tokideveloper]

I agree with blacklight447. The idea of we two using IM is to make quick proposals for the community, not quick decisions against the community.

[blacklight447]

Precisely, one extra task now will be to add the translation mailing list to this documentation page on the Qubes website. Also @tokideveloper , you mentioned you will contact me about which IM to use, will that be by mail or github?

[blacklight447]

Precisely, one extra task now will be to add the translation mailing list to this documentation page on the Qubes website. Also @tokideveloper , you mentioned you will contact me about which IM to use, will that be by mail or github?

[tokideveloper]

From @blacklight447:

Precisely, one extra task now will be to add the translation mailing list to this documentation page on the Qubes website.

Yes! Do you like to do that?

Also @tokideveloper , you mentioned you will contact me about which IM to use, will that be by mail or github?

By mail (already sent).

[tokideveloper]

From @blacklight447:

Precisely, one extra task now will be to add the translation mailing list to this documentation page on the Qubes website.

Yes! Do you like to do that?

Also @tokideveloper , you mentioned you will contact me about which IM to use, will that be by mail or github?

By mail (already sent).