Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation i18n #1318

Open
2 of 36 tasks
ddevault opened this issue Aug 13, 2017 · 27 comments
Open
2 of 36 tasks

Documentation i18n #1318

ddevault opened this issue Aug 13, 2017 · 27 comments
Labels
enhancement New feature or incremental improvement

Comments

@ddevault
Copy link
Contributor

ddevault commented Aug 13, 2017 •
edited
Loading

Leave a comment if you're interested in translating. Please be prepared to stick around and translate changes in future releases, too.

For now, only the README and FAQ are up for translation. Wait on man pages.

TL guidelines:

  • A 1:1 translation is not necessary, feel free to be creative in your translation. It's better to communicate clearly than to attempt a 1:1 translation of the English docs.
  • It may be more effective to use English terminology for technical terms. Do so if it makes things more clear.
  • If you're not sure how to translate something clearly, leave it in English.
  • In the README please indicate whether or not your translation is a WIP and link to this issue so that readers know how to help improve the TL
  • In the README, clarify the situation for speakers of that language who wish to get support. If you can volunteer to hang out in IRC and triage GitHub issues, mention your username and timezone.
  • In the README, clarify that I should be emailed in English for distro packaging help, or drop it alltogether.
  • It's okay to give the FAQ a regional spin. It doesn't have to match the English FAQ. For example, it might be appropriate to give tips on IME configuration in your language.

When translating the README, please add this subsection, translated to your language:

[Language] help

[Username] provides support in [language] on IRC and GitHub in [timezone].

[Information regarding the compelteness of the translation and a link to this issue]

We are not going to localize any messages in Sway itself - error messages and logging will remain in English so that English-speaking developers are able to interpret them when asked for assistance.
@abdelq
Copy link
Contributor

abdelq commented Aug 13, 2017 •
edited
Loading

@ddevault
Copy link
Contributor Author

Thanks, added it to the list.

@ddevault
Copy link
Contributor Author

I wrote up some TL guidelines in the OP, please review them.

@ddevault ddevault mentioned this issue Aug 14, 2017
Merged
@Hummer12007
Copy link
Contributor

Hummer12007 commented Aug 14, 2017 •
edited
Loading

@kon14
Copy link
Contributor

kon14 commented Aug 14, 2017

I plan on doing the rest soon. Usually afking in IRC (kon14), GMT+2

@ddevault
Copy link
Contributor Author

ddevault commented Aug 14, 2017 •
edited
Loading

Standard "this language is not English so here's how to get support" README subsection:

[Language] help

[Username] provides support in [language] on IRC and GitHub in [timezone].

[Information regarding the status of the translation and a link to this issue]

In Japanese I'm going to write:

日本語助け

SirCmpwnはIRCとGitHubでUTC-4に日本語助け人だ。

日本語翻訳は完成じゃない、正しくない。パッチは与えったください。

Please include similar information in your translations.

@ddevault
Copy link
Contributor Author

Sorry for frequent updates to these guidelines, i18n is a WIP.

@ddevault
Copy link
Contributor Author

I pushed a branch with some support code for localizing man pages:

https://github.com/SirCmpwn/sway/tree/localized-manpages

Unfortunately I've run into an issue with how fucking shit asciidoc is. I think I'm just going to write a new man page authoring tool this weekend.

@kon14
Copy link
Contributor

kon14 commented Aug 14, 2017

I think it would be good to discuss where man page translations should be placed and agree on a naming format before we start submitting pull requests for those.

Is a manpage directory to be created in each project the best approach? Should translation filenames be formatted as Name.Chapter.Lang.txt similarly to how README.mds are treated?

@ddevault
Copy link
Contributor Author

Take a look at the branch.

@kon14
Copy link
Contributor

kon14 commented Aug 14, 2017 •
edited
Loading

I noticed the man directories, I'm asking more in regards to the filename policy.

Since there's still no translated manpage to make an example out of I'm not sure of what's expected of us. Perhaps I'm missing something?

It would also be nice if we could get some sort of documentation versioning or at least some way for users to tell if a translation is up to date. However that would needlessly complicate things and perhaps checking the last modification date of a translation and comparing that to the original file on this end would be all that's needed to keep things up to date.

@ddevault
Copy link
Contributor Author

There is one: https://github.com/SirCmpwn/sway/blob/localized-manpages/sway/man/sway.1.ja.txt

And I'll require changes to docs to sync them across all man pages when merging PRs in the future, even if they just put in the english docs.

@ddevault
Copy link
Contributor Author

(and I will cc the relevant language maintainer on that PR)

@WhyNotHugo WhyNotHugo mentioned this issue Aug 14, 2017
Closed
@sykhro
Copy link

sykhro commented Aug 16, 2017 •
edited
Loading

Will take on the Italian translation

  • it_IT: @sykhro
    • README
    • Man pages
      • sway(1)
      • sway(5)
      • sway-bar
      • sway-input
      • swaymsg
      • swaygrab
      • swaylock
      • sway-security
    • FAQ

I plan on doing the rest soon. No IRC for now, GMT+2

@ddevault ddevault mentioned this issue Aug 16, 2017
Merged
@sykhro
Copy link

sykhro commented Aug 16, 2017

For IRC, to redirect Italian support to GitHub:
Attenzione! Il supporto Italiano su IRC al momento non è attivo. Per favore, utilizza il tracker su GitHub

@nlgranger
Copy link

@ghost
Copy link

ghost commented Aug 23, 2017 •
edited by ghost
Loading

I'll take the brazilian portuguese translation.

@ddevault
Copy link
Contributor Author

Is pt_BR intelligible to pt_PT? We should aim to kill two birds with one stone.

@ghost
Copy link

ghost commented Aug 23, 2017

There are small differences in the way some words are written (e.g., in some words, pt_PT exchanges the circumflex accent in favor of the acute accent), but the great difference resides in the slang. So I'll try my best to keep the translation neutral.

@ddevault ddevault mentioned this issue Aug 24, 2017
Closed
@gjask
Copy link

gjask commented Sep 3, 2017

I've started with Czech translation.

This was referenced Sep 3, 2017
Closed
Merged
@DarkReef
Copy link
Contributor

DarkReef commented Sep 4, 2017 •
edited
Loading

I start the translation into Russian.

@ddevault ddevault mentioned this issue Oct 20, 2017
Closed
@ddevault
Copy link
Contributor Author

I have written a man page generator which I intend to switch sway to soon. It's still missing a couple of important features (tables, mainly), but it's looking pretty good.

https://git.sr.ht/~sircmpwn/scdoc/

Once it's done we should be able to translate man pages.

@horstmannmat
Copy link

horstmannmat commented Oct 26, 2018 •
edited
Loading

I can take place, from the pt_BR, since the last user has been deleted :)

@ddevault
Copy link
Contributor Author

Great. I'll be looking into doing i18n for the man pages within a month or two.

@ghost
Copy link

ghost commented Oct 28, 2018 •
edited by ghost
Loading

I can take place, from the pt_BR, since the last user has been deleted :)

Nope, I'm right here, under a different username. This week, I was updating the README to the lastest version, and I'm waiting for the man pages to settle in order to translate them too.

Edit: fix grammar, add context.

@horstmannmat
Copy link

I can take place, from the pt_BR, since the last user has been deleted :)

Nope, I'm right here, under a different username. This week, I was updating the README to the lastest version, and I'm waiting for the man pages to settle in order to translate them too.

Edit: fix grammar, add context.

We both can do it :)
Two is better than one

@ghost
Copy link

ghost commented Oct 28, 2018

We both can do it :)

Sure :))

@horstmannmat horstmannmat mentioned this issue Nov 21, 2018
Closed
@ddevault ddevault mentioned this issue Mar 27, 2019
Open
@emersion emersion added the enhancement New feature or incremental improvement label Feb 8, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement New feature or incremental improvement
Milestone
No milestone
Development

No branches or pull requests
10 participants
@emersion @ddevault @kon14 @gjask @nlgranger @Hummer12007 @sykhro @abdelq @horstmannmat @DarkReef