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.

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

Already on GitHub? Sign in to your account

Update localization guidelines #10485

Merged
merged 5 commits into from Oct 12, 2018

Conversation

@zacharysarah
Contributor

zacharysarah commented Oct 3, 2018

馃憢 Reviews from stakeholders are welcome and encouraged! 馃檱

TL,DR

This PR updates localization docs and workflows for https://kubernetes.io. It also proposes archiving language-specific repos (k/kubernetes-docs-*).

Updates

October 09

  • Feedback from reviewers has been incorporated
  • Lazy consensus now includes a section on team cleanup (kubernetes/org#154)
  • Added a dependency: #10566, which updates k/website's top level OWNERS* and allows this PR to explicitly specify content/en/OWNERS. RESOLVED

October 10

Summary

This PR updates several aspects of localization (l10n) for Kubernetes docs:

  • Localization guidelines reflect that all l10n work now happens in k/website instead of subproject repositories.

  • Individual content/<xx> directories gain language-specific OWNERS files. This lets translation teams review and approve their own l10n-specific PRs.

  • Chinese content moves from content/cn/ to content/zh/ to conform with the ISO 639-1 naming scheme.

  • Language-specific subproject repositories will be archived.

Context

In Q3 2017, Kubernetes SIG Docs invited an independent Chinese localization project to house their project in k/website. SIG Docs was unprepared for the introduction of Chinese-language content, due to both the amount of PRs and the lack of Chinese fluency on the part of k/website's maintainers.

To enable translation work to continue while SIG Docs solved for infrastructure support and a scalable l10n workflow, SIG Docs proposed the creation of a language-specific subproject for Chinese content (kubernetes-docs-zh). The goal was for translation work to continue without creating an undue burden on either the Chinese l10n (via a backlog of unapproved PRs) or on SIG Docs maintainers (unable to provide meaningful review of Chinese content).

SIG Architecture also approved the creation of two additional repos for new localization projects in Japanese (k/kubernetes-docs-ja) and Korean (k/kubernetes-docs-ko).

In Q3 2018, while solving for how to pass source content and translated output between repos, @zparnold proposed and implemented a language label bot. The bot automatically assigns labels to PRs based on the content/* filepaths of pull requests, allowing reviewers to filter pull requests by language. For example, see this list of PRs with Korean content.

UPDATE: Per @cblecker in #10485 (comment), Prow natively supports automatic label assignment by language. I've updated this PR accordingly. The implementation differs from the original proposal, but the strategic effect remains the same.

The combination of native multilingual support and automated language labeling allows SIG Docs to consolidate l10n workflows in a single repository: k/website. This strategy scales appropriately with increasing numbers of localizations. The alternative requires SIG Docs to enforce common standards for synchronizing source and output across multiple, non-forked repos with disparate branching structures and non-identical milestones. These strategies are unnecessarily complex and do not scale well.

Consolidating workflows is a good idea. Let's do it.

There is one notable downside of archiving language-specific repos: absent some finely-tuned git commands, l10n teams could lose their commit histories by moving files from one repo to another. This is avoidable, but it does require git expertise. (馃憟 @mistyhacks) It's also not the end of the world, but it is kind of a bummer.

Easy file previews

Dependencies

PRs in k/website

PR Description 鉁旓笍
#10566 Update OWNERS* to enable content/en/OWNERS 鉁旓笍

Impacts to other Kubernetes SIGs

PR SIG Impact
kubernetes/community#2753 community Remove language-specific subprojects from SIG Docs info
kubernetes/test-infra#9732 test-infra Remove language-specific subproject repos from Prow configuration
kubernetes/org#154 Kubernetes org Archive language-specific repos and teams

Lazy consensus

If stakeholders do nothing by Friday, October 12:

@k8sio-netlify-preview-bot

This comment has been minimized.

Collaborator

k8sio-netlify-preview-bot commented Oct 3, 2018

Deploy preview for kubernetes-io-master-staging ready!

Built with commit 76a9621

https://deploy-preview-10485--kubernetes-io-master-staging.netlify.com

@k8sio-netlify-preview-bot

This comment has been minimized.

Collaborator

k8sio-netlify-preview-bot commented Oct 3, 2018

Deploy preview for kubernetes-io-master-staging failed.

Built with commit a6cf9f4

https://app.netlify.com/sites/kubernetes-io-master-staging/deploys/5bc10f4473f2cf64dde20c56

@k8s-ci-robot k8s-ci-robot added size/L and removed size/M labels Oct 4, 2018

@ClaudiaJKang ClaudiaJKang referenced this pull request Oct 5, 2018

Closed

ONWERS under contents/ko directory #46

0 of 2 tasks complete

@k8s-ci-robot k8s-ci-robot added size/XL and removed size/L labels Oct 6, 2018

@k8s-ci-robot k8s-ci-robot added size/L and removed size/XL labels Oct 6, 2018

@zacharysarah zacharysarah changed the title from [WIP] Update localization guidelines to Update localization guidelines Oct 7, 2018

@zacharysarah

This comment has been minimized.

Contributor

zacharysarah commented Oct 7, 2018

Stakeholders

Chinese localization

@tengqm, @markthink, @hanjiayao

Japanese localization

@cstoku, @MasayaAoyama, @tnir

Korean localization

@ClaudiaJKang, @gochist, @ianychoi

SIG Architecture

Should the Kubernetes org fork the language label app into the kubernetes GitHub organization?

@cblecker, @kubernetes/sig-architecture-pr-reviews
/sig architecture

SIG Community

@parispittman, @kubernetes/community-reviewers
/sig community

SIG Docs

@Bradamant3, @chenopis, @jaredbhatti, @zparnold
@mistyhacks for git expertise in preserving commit histories between repos

SIG Test-Infra

@spiffxp, @kubernetes/test-infra-reviewers
/sig test-infra

General interest

@caniszczyk, @dankohn

config.toml Outdated
@@ -7,7 +7,7 @@ enableRobotsTXT = true
disableKinds = ["taxonomy", "taxonomyTerm"]
ignoreFiles = [ "^OWNERS$", "README.md", "^node_modules$", "content/en/docs/doc-contributor-tools" ]
ignoreFiles = [ "^OWNERS$", "README*.md", "^node_modules$", "content/en/docs/doc-contributor-tools" ]

This comment has been minimized.

@zacharysarah

zacharysarah Oct 7, 2018

Contributor

Does this regex correctly exclude examples like README-ko.md?

@zparnold

This comment has been minimized.

@cstoku

cstoku Oct 7, 2018

Member

^OWNERS$ seems to copy the OWNERS file in the subdirectory. I think OWNERS$ is correct.

This comment has been minimized.

@zacharysarah

zacharysarah Oct 8, 2018

Contributor

@cstoku Thanks--it's the addition of language-specific READMEs (for example, README-ja.md) for which I want to verify the exclusion with "README*.md".

This comment has been minimized.

@zacharysarah

zacharysarah Oct 8, 2018

Contributor

@zparnold 鈽濓笍 PTAL

This comment has been minimized.

@mistyhacks

mistyhacks Oct 9, 2018

Contributor

I think you want to tighten this regex. You want to match things that:

  • start with README
  • end with .md
  • Don't have -[a-z][a-z]

So: README\.md gets exactly README.md without any others.

If you wanted to match only the language-specific ones: README[-]+[a-z]*\.md That looks for things with 1 or more hyphen and then 0 or more letters before the .md

This comment has been minimized.

@zacharysarah

zacharysarah Oct 9, 2018

Contributor

@mistyhacks Thanks for the review!

This comment has been minimized.

@tnir

tnir Oct 10, 2018

Member

@zacharysarah Use \\ instead of \ in a toml file, like "README[-]+[a-z]*\\.md".

@gochist

I have questions

Each l10n repository must have branches for the different Kubernetes documentation release versions, matching the branches in the main [kubernetes/website](https://github.com/kubernetes/website) documentation repository. For example, the kubernetes/website `release-1.10` branch (https://github.com/kubernetes/website/tree/release-1.10) has a corresponding branch in the kubernetes/kubernetes-docs-zh repository (https://github.com/kubernetes/kubernetes-docs-zh/tree/release-1.10). These version branches keep track of the differences in the documentation between Kubernetes versions.
Teams are free to use any branching strategy for work in progress. For example, a German localization team might use source files from `{{< release-branch >}}`, but work in `dev-{{< release-branch >}}-de-1.0` before squashing commits in a single PR against `{{< release-branch >}}`.

This comment has been minimized.

@gochist

gochist Oct 7, 2018

Member

In this example, which repository does the dev-{{< release-branch >}}-de-1.0 branch belong to? If it is k/website, does l10n team have permission to create those branch?

This comment has been minimized.

@zacharysarah

zacharysarah Oct 8, 2018

Contributor

@gochist 馃憢

which repository does the branch belong to?

Yes, it's k/website.

does l10n team have permission to create those branch?

Yes. 馃憤

It's probably best to treat a development branch for translation the same as any other long-running collaborative branch (for example, the release branches for 1.11 and 1.10: #9171, #7818).

Normally we require folks to open PRs on a fork of k/website, but for collaborative projects like localizations I think it's better to treat them like release branches and open directly against k/website.

A development branch for 1.12 source would require an open PR against https://github.com/kubernetes/website/tree/release-1.12, which Individual contributors would then use as the base for their own PRs. A team needs to agree on who opens and maintains the PR--by keeping it current with its parent branch, resolving merge conflicts, and setting expectations for when to merge it--but that can be anyone, with no special permissions required.

We should absolutely specify this in the docs. 馃憤 I'll update this PR accordingly. Great question!

Show resolved Hide resolved content/en/docs/contribute/localization.md Outdated
Show resolved Hide resolved content/en/docs/contribute/localization.md
@cstoku

This comment has been minimized.

Member

cstoku commented Oct 7, 2018

About the overview of this issue, is the following content correct?


Now:

* [ ]  Add an OWNERS file to `/content/ja/` that duplicates [`kubernetes-docs-ko:OWNERS`](https://github.com/kubernetes/kubernetes-docs-ja/blob/master/OWNERS)

Revised:

* [ ]  Add an OWNERS file to `/content/ja/` that duplicates [`kubernetes-docs-ja:OWNERS`](https://github.com/kubernetes/kubernetes-docs-ja/blob/master/OWNERS)

Now:

  • Archive the kubernetes/kubernetes-docs-ja repository using admin permissions

    • Make one final commit of kubernetes-docs-ko:content/ja/ to k/website
  • Archive the kubernetes/kubernetes-docs-zh repository using admin permissions

    • Make one final commit of kubernetes-docs-ko:content/zh/ to k/website
* [ ]  Archive the [`kubernetes/kubernetes-docs-ja`](https://github.com/kubernetes/kubernetes-docs-ko) repository using admin permissions

  * [ ]  Make one final commit of `kubernetes-docs-ko:content/ja/` to `k/website`
* [ ]  Archive the [`kubernetes/kubernetes-docs-zh`](https://github.com/kubernetes/kubernetes-docs-ko) repository using admin permissions

  * [ ]  Make one final commit of `kubernetes-docs-ko:content/zh/` to `k/website`

Revised:

  • Archive the kubernetes/kubernetes-docs-ja repository using admin permissions

    • Make one final commit of kubernetes-docs-ja:content/ja/ to k/website
  • Archive the kubernetes/kubernetes-docs-zh repository using admin permissions

    • Make one final commit of kubernetes-docs-zh:content/zh/ to k/website
* [ ]  Archive the [`kubernetes/kubernetes-docs-ja`](https://github.com/kubernetes/kubernetes-docs-ja) repository using admin permissions

  * [ ]  Make one final commit of `kubernetes-docs-ja:content/ja/` to `k/website`
* [ ]  Archive the [`kubernetes/kubernetes-docs-zh`](https://github.com/kubernetes/kubernetes-docs-zh) repository using admin permissions

  * [ ]  Make one final commit of `kubernetes-docs-zh:content/zh/` to `k/website`
Upstream contributions are welcome and encouraged!
For the sake of efficiency, limit upstream contributions to a single pull request per week, containing a single [squashed commit](https://github.com/todotxt/todo.txt-android/wiki/Squash-All-Commits-Related-to-a-Single-Issue-into-a-Single-Commit).
SIG Docs welcomes ustream contributions and corrections to the English source! For the sake of efficiency, limit upstream contributions to a single pull request per week, containing a single [squashed commit](https://github.com/todotxt/todo.txt-android/wiki/Squash-All-Commits-Related-to-a-Single-Issue-into-a-Single-Commit).

This comment has been minimized.

@tnir

tnir Oct 8, 2018

Member

s/ustream/upstream/

This comment has been minimized.

@zacharysarah

zacharysarah Oct 8, 2018

Contributor

@tnir Even editors are not immune. 馃槅 馃檱

```shell
mkdir -p content/de/docs/tutorials
cp content/en/docs/tutorials/kubernetes-basics.md content/de/docs/tutorials/kubernetes-basics.md
cp content/en/docs/tutorials/kubernetes-basics.md content/de/docs/tutorials/kubernetes-basics.md

This comment has been minimized.

@tnir

tnir Oct 8, 2018

Member

You don't need to add an extra white space here 馃槃

@k8s-ci-robot k8s-ci-robot added the lgtm label Oct 12, 2018

@k8s-ci-robot

This comment has been minimized.

k8s-ci-robot commented Oct 12, 2018

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: kbarnard10

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@k8s-ci-robot k8s-ci-robot merged commit abcee2d into kubernetes:master Oct 12, 2018

3 checks passed

cla/linuxfoundation zacharysarah authorized
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
tide In merge pool.
Details

@zacharysarah zacharysarah deleted the zacharysarah:update-l10n-guidelines branch Oct 12, 2018

@tnir

This comment has been minimized.

Member

tnir commented Oct 12, 2018

@zacharysarah @kbarnard10 馃憤 馃帀

While just checked zh and ko, https://kubernetes.io/zh/ is not found (404) (/cn/ is still available) and https://kubernetes.io/ko/ looks wierd (features and case studies).

@zparnold

This comment has been minimized.

Member

zparnold commented Oct 12, 2018

@tnir

This comment has been minimized.

Member

tnir commented Oct 13, 2018

@zparnold Thanks 馃槃

@zacharysarah

This comment has been minimized.

Contributor

zacharysarah commented Oct 15, 2018

@tnir

This comment has been minimized.

Member

tnir commented Oct 15, 2018

@zacharysarah Yes, after #10610 (and might be other PRs), now we can see that it works well 馃帀馃帀馃帀

@markthink

This comment has been minimized.

Member

markthink commented Oct 15, 2018

@zacharysarah I can't create a branch PUSH code for myself, I can't complete the update operation, suggesting that I didn't pass the cla check. In fact, this problem should not exist.

Counting objects: 4, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 11.18 KiB | 0 bytes/s, done.
Total 4 (delta 2), reused 0 (delta 0)
remote: Resolving deltas: 100% (2/2), completed with 1 local object.
remote: error: GH006: Protected branch update failed for refs/heads/release-1.12-zh.
remote: error: Required status check "cla/linuxfoundation" is expected.
To https://github.com/kubernetes/kubernetes-docs-zh.git
 ! [remote rejected]   release-1.12-zh -> release-1.12-zh (protected branch hook declined)
error: failed to push some refs to 'https://github.com/kubernetes/kubernetes-docs-zh.git'

PUSH is designed to update the latest code base, and managing documents is sometimes necessary.

The impact of this issue锛欰lthough it has been successfully switched from cn to zh directory here, kubernetes-docs-zh does not push update permissions, and submitting PR operations to merge documents is not particularly convenient.

@zacharysarah

This comment has been minimized.

Contributor

zacharysarah commented Oct 15, 2018

@markthink Please open your comment as a new issue so we can resolve it separately. Thanks in advance.

@brucehex

This comment has been minimized.

brucehex commented Oct 18, 2018

@zacharysarah ok, thank you.

ClaudiaJKang added a commit to ClaudiaJKang/website that referenced this pull request Oct 18, 2018

New link about Localizing Kubernetes Documentation
This commit adds a link about Localizing Kubernetes Documentation in
README.md's Contributing to the docs section.

Fixed : kubernetes#10485, kubernetes#10622

Signed-off-by: Claudia J. Kang <claudiajkang@gmail.com>

ClaudiaJKang added a commit to ClaudiaJKang/website that referenced this pull request Oct 18, 2018

Update l10n guide about adding l10n README files.
This commit adds a link process about the l10n README files in
localization.md.

Fixed : kubernetes#10485, kubernetes#10622

Signed-off-by: Claudia J. Kang <claudiajkang@gmail.com>

k8s-ci-robot added a commit that referenced this pull request Oct 23, 2018

Update l10n READMEs link (#10669)
* New link about Localizing Kubernetes Documentation

This commit adds a link about Localizing Kubernetes Documentation in
README.md's Contributing to the docs section.

Fixed : #10485, #10622

Signed-off-by: Claudia J. Kang <claudiajkang@gmail.com>

* Update l10n guide about adding l10n README files.

This commit adds a link process about the l10n README files in
localization.md.

Fixed : #10485, #10622

Signed-off-by: Claudia J. Kang <claudiajkang@gmail.com>

@zacharysarah zacharysarah referenced this pull request Nov 8, 2018

Closed

Prow doesn't automatically apply language labels #10097

1 of 2 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment