taichi-dev/docs.taichi.graphics

Migrate the zh-cn existing docs

rexwangcc opened this issue · 1 comments

Once #21 is done, we need to migrate the existing translated docs in Zh-cn. This can be done in multiple PRs iteratively, which is easier to be reviewed.

Acceptance Criteria:

  • The existing docs are migrated
  • Cross-check with the up-to-date en documentation, any outdated translation shall be removed or left blank.
  • The credits of the docers who have contributed shall be honored properly in this repo too.
  • Update the current taichi.graphics website:
    • Move the stack to the react based docusaurus or Gatsby or other MDX based frameworks, to better align with the existing components and libraries (some of which are internal).
    • Separate the docs and API into two different categories, both are linked from a higher level website (which will become the future taichi.graphics).
    • Clean up the main repo's doc related PRs. (We'd better create a mirror issue in the main repo before starting this task)
    • Add instructions for contributors about how to contribute under the new structure, in both docs and the main repo. (We'd better create a mirror issue in the main repo before starting this task)

The targeted docs infrastruture is illustrated by the following diagram:

Update: Crowdin integration is now in a relatively stable state, now contributors could go to https://crowdin.com/project/taichi-programming-language/zh-CN# to claim untranslated files and translate online, translations will be reviewed on Crowdin and automatically get opened as PRs from branch l10n_master to master every 6 hours. Since the files matchers are wildcards in crowdin.yml, any new docs or updated doc strings will be automatically detected by Crowdin.

Thank you @yuanming-hu @isdanni both for providing insights into this and helping set up the workflow!! I'm going to close this issue and rely on #22 to track the work of migrating the existing PO files, hopefully by Thanksgiving.

I noticed there are stale PRs in the main repo that updates the docs that we should either merge or close and mirror in this repo; there are also outdated docs in this repo compared to the docs/ in the main repo. Once we finish the migration, we may consider take the docs folder out of the main repo ASAP to avoid inconsistent states.

Originally posted by @rexwangcc in https://github.com/taichi-dev/taichi.graphics/issues/21#issuecomment-730809476

As the above mentioned, while we are migrating the docs, we need to keep 2 things in mind:

  • The existing zh-cn docs are outdated and may not match what's in the en docs in this repo. When we encocutner this, always use the en docs as the source of truth, even if that means we need to throw away some of the exising zh-cn docstring.
  • The en docs in this repo can also be outdated compared with the en docs/ in the main repo. Whenever we encounter this, we shall open a PR to update the en docs in this repo before we move forward with any translations to avoid duplicated work.