-
Notifications
You must be signed in to change notification settings - Fork 14.5k
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’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update localization guidelines #10485
Update localization guidelines #10485
Conversation
Deploy preview for kubernetes-io-master-staging ready! Built with commit 76a9621 https://deploy-preview-10485--kubernetes-io-master-staging.netlify.com |
Deploy preview for kubernetes-io-master-staging failed. Built with commit a6cf9f4 https://app.netlify.com/sites/kubernetes-io-master-staging/deploys/5bc10f4473f2cf64dde20c56 |
StakeholdersChinese localization@tengqm, @markthink, @hanjiayao Japanese localizationKorean localization@claudiajkang, @gochist, @ianychoi SIG ArchitectureShould the Kubernetes org fork the language label app into the kubernetes GitHub organization? @cblecker, @kubernetes/sig-architecture-pr-reviews SIG Community@parispittman, @kubernetes/community-reviewers SIG Docs@Bradamant3, @chenopis, @jaredbhatti, @zparnold SIG Test-Infra@spiffxp, @kubernetes/test-infra-reviewers General interest |
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" ] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does this regex correctly exclude examples like README-ko.md
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
^OWNERS$
seems to copy the OWNERS file in the subdirectory. I think OWNERS$
is correct.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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"
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@zparnold ☝️ PTAL
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@MistyHacks Thanks for the review! ✨
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@zacharysarah Use \\
instead of \
in a toml file, like "README[-]+[a-z]*\\.md"
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 >}}`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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! ✨
About the overview of this issue, is the following content correct? Now:
Revised:
Now:
Revised:
|
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). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
s/ustream/upstream/
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You don't need to add an extra white space here 😄
[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 |
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). |
It might be a CDN cache issue
…On Fri, Oct 12, 2018 at 4:12 PM Takuya N ***@***.***> wrote:
@zacharysarah <https://github.com/zacharysarah> @kbarnard10
<https://github.com/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).
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#10485 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AE81SOYC1Qp5zigcbwPY_MP2OJe5o4fbks5ukSHCgaJpZM4XHIwZ>
.
|
@zparnold Thanks 😄 |
@zacharysarah Yes, after #10610 (and might be other PRs), now we can see that it works well 🎉🎉🎉 |
@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.
|
@markthink Please open your comment as a new issue so we can resolve it separately. Thanks in advance. |
@zacharysarah ok, thank you. |
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 <[email protected]>
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 <[email protected]>
* 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 <[email protected]> * 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 <[email protected]>
* Update localization guidelines for language labels Continuing work Continuing work Continuing work More work in progress Add local OWNERS folders Add an OWNERS file to Chinese Remove shortcode for repos Add Japanese Alphabetize languages, change weights accordingly More updates Add Korean in Korean Add English to languageName Feedback from gochist Move Chinese content from cn/ to zh/ Move OWNERS from cn/ to zh/ Resolve merge conflicts by updating from master Add files back in to prep for resolution After rebase on upstream/master, remove files Review and update localization guidelines Feedback from gochist, tnir, cstoku Add a trailing newline to content/ja/OWNERS Add a trailing newline to content/zh/OWNERS Drop requirement for GH repo project Clarify language about forks/branches Edits and typos Remove a shortcode specific to a multi-repo language setup Update aliases and owners Add explicit OWNERS for content/en Migrate content from Chinese repo, update regex in config.toml Remove untranslated strings Add trailing newline to content/en/OWNERS Add trailing newlines to OWNERS files add Jaguar project description (kubernetes#10433) * add Jaguar project description [Jaguar](https://gitlab.com/sdnlab/jaguar) is an open source solution for Kubernetes's network based on OpenDaylight. Jaguar provides overlay network using vxlan and Jaguar CNIPlugin provides one IP address per pod. * Minor newline tweak blog post for azure vmss (kubernetes#10538) Add microk8s to pick-right-solution.md (kubernetes#10542) * Add microk8s to pick-right-solution.md Microk8s is a single-command installation of upstream Kubernetes on any Linux and should be included in the list of local-machine solutions. * capitalized Istio Add microk8s to foundational.md (kubernetes#10543) * Add microk8s to foundational.md Adding microk8s as credible and stable alternative to get started with Kubernetes on a local machine. This is especially attractive for those not wanting to incur the overhead of running a VM for a local cluster. * Update foundational.md Thank you for your suggestions! LMK if this works now? * Rewrote first paragraph And included a bullet list of features of microk8s * Copyedit fix typo (kubernetes#10545) Fix the kubectl subcommands links. (kubernetes#10550) Signed-off-by: William Zhang <[email protected]> Fix command issue (kubernetes#10515) Signed-off-by: mooncake <[email protected]> remove imported community files per issue 10184 (kubernetes#10501) networking.md: Markdown fix (kubernetes#10498) Fix front matter, federation command-line tools (kubernetes#10500) Clean up glossary entry (kubernetes#10399) update slack link (kubernetes#10536) typo in StatefulSet docs (kubernetes#10558) fix discription about horizontal pod autoscale (kubernetes#10557) Remove redundant symbols (kubernetes#10556) Fix issue kubernetes#10520 (kubernetes#10554) Signed-off-by: William Zhang <[email protected]> Update api-concepts.md (kubernetes#10534) Revert "Fix command issue (kubernetes#10515)" This reverts commit c02a7fb. Update memory-constraint-namespace.md (kubernetes#10530) update memory request to 100MiB corresponding the yaml content Blog: Introducing Volume Snapshot Alpha for Kubernetes (kubernetes#10562) * blog post for azure vmss * snapshot blog post Resolve merge conflicts in OWNERS* Minor typo fix (kubernetes#10567) Not sure what's supposed to be here, proposing removing it. * Feedback from gochist Tweaks to feedback * Feedback from ClaudiaJKang
* Update localization guidelines for language labels Continuing work Continuing work Continuing work More work in progress Add local OWNERS folders Add an OWNERS file to Chinese Remove shortcode for repos Add Japanese Alphabetize languages, change weights accordingly More updates Add Korean in Korean Add English to languageName Feedback from gochist Move Chinese content from cn/ to zh/ Move OWNERS from cn/ to zh/ Resolve merge conflicts by updating from master Add files back in to prep for resolution After rebase on upstream/master, remove files Review and update localization guidelines Feedback from gochist, tnir, cstoku Add a trailing newline to content/ja/OWNERS Add a trailing newline to content/zh/OWNERS Drop requirement for GH repo project Clarify language about forks/branches Edits and typos Remove a shortcode specific to a multi-repo language setup Update aliases and owners Add explicit OWNERS for content/en Migrate content from Chinese repo, update regex in config.toml Remove untranslated strings Add trailing newline to content/en/OWNERS Add trailing newlines to OWNERS files add Jaguar project description (kubernetes#10433) * add Jaguar project description [Jaguar](https://gitlab.com/sdnlab/jaguar) is an open source solution for Kubernetes's network based on OpenDaylight. Jaguar provides overlay network using vxlan and Jaguar CNIPlugin provides one IP address per pod. * Minor newline tweak blog post for azure vmss (kubernetes#10538) Add microk8s to pick-right-solution.md (kubernetes#10542) * Add microk8s to pick-right-solution.md Microk8s is a single-command installation of upstream Kubernetes on any Linux and should be included in the list of local-machine solutions. * capitalized Istio Add microk8s to foundational.md (kubernetes#10543) * Add microk8s to foundational.md Adding microk8s as credible and stable alternative to get started with Kubernetes on a local machine. This is especially attractive for those not wanting to incur the overhead of running a VM for a local cluster. * Update foundational.md Thank you for your suggestions! LMK if this works now? * Rewrote first paragraph And included a bullet list of features of microk8s * Copyedit fix typo (kubernetes#10545) Fix the kubectl subcommands links. (kubernetes#10550) Signed-off-by: William Zhang <[email protected]> Fix command issue (kubernetes#10515) Signed-off-by: mooncake <[email protected]> remove imported community files per issue 10184 (kubernetes#10501) networking.md: Markdown fix (kubernetes#10498) Fix front matter, federation command-line tools (kubernetes#10500) Clean up glossary entry (kubernetes#10399) update slack link (kubernetes#10536) typo in StatefulSet docs (kubernetes#10558) fix discription about horizontal pod autoscale (kubernetes#10557) Remove redundant symbols (kubernetes#10556) Fix issue kubernetes#10520 (kubernetes#10554) Signed-off-by: William Zhang <[email protected]> Update api-concepts.md (kubernetes#10534) Revert "Fix command issue (kubernetes#10515)" This reverts commit c02a7fb. Update memory-constraint-namespace.md (kubernetes#10530) update memory request to 100MiB corresponding the yaml content Blog: Introducing Volume Snapshot Alpha for Kubernetes (kubernetes#10562) * blog post for azure vmss * snapshot blog post Resolve merge conflicts in OWNERS* Minor typo fix (kubernetes#10567) Not sure what's supposed to be here, proposing removing it. * Feedback from gochist Tweaks to feedback * Feedback from ClaudiaJKang
👋 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
Added a dependency: Clean up OWNERS* files with permissions by alias #10566, which updates k/website's top level OWNERS* and allows this PR to explicitly specifyRESOLVEDcontent/en/OWNERS
.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/
tocontent/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. (:point_left: @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
content/en/OWNERS
Impacts to other Kubernetes SIGs
Lazy consensus
If stakeholders do nothing by Friday, October 12:
/content/cn/
tocontent/zh/
/content/ko/
that duplicateskubernetes-docs-ko:OWNERS
/content/ja/
that duplicateskubernetes-docs-ko:OWNERS
/content/zh/
as a placeholderkubernetes/kubernetes-docs-ja
repository using admin permissionskubernetes-docs-ko:content/ja/
tok/website
kubernetes/kubernetes-docs-ko
repository using admin permissionskubernetes-docs-ko:content/ko/
tok/website
kubernetes/kubernetes-docs-zh
repository using admin permissionskubernetes-docs-ko:content/zh/
tok/website
@kubernetes/sig-docs-en-reviewsCreate an OWNERS_ALIAS for sig-docs-pr-reviews