superseriousbusiness / gotosocial

Fast, fun, small ActivityPub server.
https://docs.gotosocial.org
GNU Affero General Public License v3.0
3.85k stars 339 forks source link

[docs] add zh docs #3507

Closed CDN18 closed 3 weeks ago

CDN18 commented 3 weeks ago

Description

This PR adds a currently-up-to-date Simplified Chinese support to the GotSocial documentation. The Chinese documentation will be available at https://docs.gotosocial.org/zh-cn/.

Key Changes

Note

The Translation Workflow

To add a new document translation, fork the repo and create a docs/locales/<language_code> directory in the repository and add the translated documents in the same structure. Refer to docs/locales/zh to establish the corresponding readthedocs and mkdocs configurations. (The main documentation has a language switch feature, so you also need to update the corresponding language item in the main documentation configuration.) Then request the maintainers to create and configure a gotosocial-<language_code> project in Read the Docs to enable the language variant.

To update translations, simply make changes and raise a PR as you would with the original documentation. To avoid too many "Translation Update" PRs clogging the merging queue, consider suggesting a maximum update frequency, like every two weeks or once a month.

TODO

  1. As translations may inevitably lag behind the original documentation, it's important to include a note in the translated documents informing readers that the content may be outdated and that they should consult the English version for the most recent information. Additionally, if a language version hasn’t been updated for too long, consider removing it (or disabling the translation). You could set a minimum update interval, such as six months or five 0.x version updates. Will make a seperate PR if this is acceptable,
  2. Specifically, the Chinese Swagger documentation uses the translation I recently created for my own instance. This Swagger documentation aligns strictly with the original in terms of specifications. I’ve reverted all instance-specific changes to a neutral state. However there's a noticeable difference that the translated Swagger uses shorter titles as summary and puts detailed descriptions in the description section. For example, in the /.well-known/host-meta endpoint, the original title is "Returns a compliant hostmeta response to web host metadata queries," while in the Chinese version (translated back into English here), the title is "Get host-meta response," with the original title moved to the beginning of the description. This change was made for personal reasons, but given the large size of the Swagger file (over 10,000 lines), it’s challenging to revert this change. Since the meaning remains the same and no information is lost, I believe this does not impact comprehension.
  3. If needed, I am willing to draft separate guidance on creating and maintaining documentation translations for submission in another PR.
  4. While translating this document, I noticed several areas in the original GotoSocial documentation that do not reflect recent changes and new features. If time permits, I will submit a separate PR with the corresponding changes and use this to test the translation update workflow.
  5. Since the media resources are shared, the diagrams in the Chinese documentation are currently in English. I will provide translated versions of these diagrams in a future PR.

Checklist

Please put an x inside each checkbox to indicate that you've read and followed it: [ ] -> [x]

If this is a documentation change, only the first checkbox must be filled (you can delete the others if you want).

CDN18 commented 3 weeks ago

Below is the preview of the zh version of the gts document on Read the Docs. Temperately available until the pr is closed: https://gts-doc-test.readthedocs.io

gts chinese doc preview

NyaaaWhatsUpDoc commented 3 weeks ago

god damn, this is brilliant work!

tsmethurst commented 3 weeks ago

This is amazing, thank you!!! Will have a look through properly tomorrow, but the new structure and suggestions seem very sensible :)

tsmethurst commented 3 weeks ago

I've squash merged it! Thank you very very much for this brilliant work!

CDN18 commented 3 weeks ago

Hooray! I'll do my best to keep up with maintaining this translation and get started on the TODO items!