Add Simplified Chinese Documentation

[Yuerchu]

Hi!

I noticed that the documentation currently lacks support for Simplified Chinese (zh-CN). As a Simplified Chinese speaker, I would love to help translate the documentation into Simplified Chinese to make this project more accessible to users and contributors from China and other regions where Simplified Chinese is widely used.

I have already translated some content, such as:
NiceGUI 文本元素 NiceGUI Text Elements
NiceGUI ui.label

This is a translation of what was written on my personal blog. Since my blog is based on WordPress, it is not easy to preview the interactive components of NiceGUI.

I hope to upload my translated documentation to the repository in the form of a Pull Request, so that users can choose between Simplified Chinese or English on the official NiceGUI website.

[Yuerchu]

Like this (changed by F12 develop mode)

[rodja]

How would that be done? Is it a complex change or could you create a pull request to show what you mean, @python-and-fiction ?

[python-and-novella]

Not only chinese, any non-english document is needed for others.
So, we can add more pages of document which is translated into other language.
It looks like fastapi's website.
https://fastapi.tiangolo.com/
I can click language switch to visit chinese version website whose src is https://github.com/fastapi/fastapi/tree/master/docs/zh .
Some pages is still english, but someone wants to translate, they can create pr more easily.

[rodja]

We are not sure what's the best way to implement this. Just copying the website and letting people start creating pull requests feels not right. Ideally we we would have some translation lookup table which is used in the main documentation to pick the right language. Each table could then be auto-translated with an llm and then fine-tuned with pull requests without needing to touch the page content.

[python-and-novella]

I think rodja is right. The best way is automatic translating.
Maybe chinese user can do this by using llm tools? @Yuerchu

[Yuerchu]

I think rodja is right. The best way is automatic translating.
Maybe chinese user can do this by using llm tools? @Yuerchu

I also recommend using llm, but I personally suggest that, if capable, allowing friends from the open source community to review it to find any potential translation errors. For example, certain proper nouns like "Quasar" might be force translated as "类星体" by translation programs, which is incorrect.

[Yuerchu]

I have acquired the domain nicegui.cn and built an official counterpart website using this repository. The site is hosted on servers in Hong Kong, China, optimized for fast access from mainland China. While currently working to localize it into Simplified Chinese, most content remains in English. I'm exploring a more sustainable translation strategy, as directly modifying the source code for translations complicates synchronization with upstream updates of NiceGUI.

我购买了一个域名：nicegui.cn ，并使用此仓库搭建起了一个官方同款的网站。部署的服务器在中国香港，在中国大陆的朋友能很快地访问这个网站。我正在尝试把它翻译成简体中文，虽然目前来看，大部分内容依旧是 English. 但我仍旧在探索一种更好的翻译方案，因为目前我直接修改相关代码来完成翻译，这使得NiceGUI在更新时，此文档的更新也是灾难级的。

[evnchn]

My proposal:

Have a MultilingualString class, when invoke str(), reads the locale set and returns the string of such locale.

Would require minimal changes to the documentation code, which I'll be frank, is probably beyond my abilities to read, let alone edit 😅

[evnchn]

https://github.com/evnchn/nicegui-i18n-poc

@Yuerchu let's see if this can work. Provided we call str() before passing into any UI element (f-string does that implicitly) then the MultilingualString class figures out the user language and returns the appropriate string.

[Yuerchu]

@evnchn Yes, I agree this approach is also a viable option. However, I think using ui.run_javascript('navigator.language') to retrieve the user's language might be better? After detecting the user's language, we could have FastAPI return the corresponding language JSON static files, then hand them over to NiceGUI for rendering.

[evnchn]

There is no JSON file. Instead, the documentation is handled via Python and some decorator magic logic that I don't want to understand.

https://github.com/zauberzeug/nicegui/blob/main/website%2Fdocumentation%2Fcontent%2Faudio_documentation.py

Therefore, I think if we can override the string to be MultilingualString, then we can handle the i18n one step before the documentation display logic kicks in, making life easier for me.

[evnchn]

Have a MultilingualString class, when invoke str(), reads the locale set and returns the string of such locale.

We probably don't even need a class. A function would do. Imagine function return_correct_string(default, dict_of_translations)

[Yuerchu]

Directly modifying the source code of the NiceGUI repository still seems problematic. Especially when rendering the documentation for NiceGUI methods, it directly reads the docstrings from elements rather than storing them in separate documentation files. This means it can only support a single language. If we forcibly change these docstrings to another language (like Simplified Chinese), then everyone would only see the Simplified Chinese documentation on the official website, and even get only Chinese syntax hints in newer IDEs 😅. Unless we create a separate branch and aggressively modify NiceGUI's source code, I can't find another way to achieve this.

[evnchn]

Thought: But then if you talk about "docstring", since it is a string, we are doomed since day1, since (1) each function have 1 docstring, (2) even if there were 2 docstrings, the IDE won't be smart enough to switch between the two.

It may be temping to just have both English and Chinese, but (1) it gets long and (2) it gets longer with more language support, which we are opening the floodgates to with MultilingualString

@Yuerchu can you check other libraries which offer documentation in both Chinese and English, how they handle the docstring issue?

---

But for this:

@doc.demo('Control the audio element', '''
    This demo shows how to play, pause and seek programmatically.
''')

I honestly don't see the issue with:

@doc.demo(MultilingualString("Control the audio element", {"zh": "控制音频元素"}), 
          MultilingualString('''
    This demo shows how to play, pause and seek programmatically.
''', {"zh": "此演示展示如何以编程方式播放、暂停和跳转。"}))

Or maybe I'm dumb 😅. What do I know 🤷‍♂️.

[falkoschindler]

As you have noticed, NiceGUI's documentation is based on a custom framework that allows to create documentation pages with very little overhead. Take https://github.com/zauberzeug/nicegui/blob/main/website/documentation/content/label_documentation.py for example. There's a decorator @doc.demo() that can take a UI element or a function and consumes its docstring. Alternatively, you can specify a title and a description. The decorated function defines an interactive demo. Last but not least, doc.reference() auto-generates a reference section.

A disadvantage of this system is that there is no separate content management system other that the Python code itself - docstrings and *_documentation.py files. To add more languages, we would somehow need to replace docstrings with translations, or replace the whole system altogether. But I think there's so much value in having a low-threshold documentation where you can easily add a documentation page after implementing a new UI element. An i18n solution shouldn't come at a too high cost in this regard.

Which brings me to a rather fundamental question: I know that popular libraries like FastAPI take translation very seriously. And I know that not everyone is speaking English (about 70-80%). Maybe Chinese (20-25%) already covers most of the non-english speaking developers. A next step could be Spanish, Japanese and Russian. But we might not need 20 or so languages.

Let me cite some pros and cons from Claude.ai:

Arguments for minimal manual translation (English + Chinese only):

• Quality of automatic translation tools: Modern translation tools like DeepL and Google Translate have significantly improved for technical content, especially for major languages
• Maintenance burden: Each additional language multiplies the maintenance effort when documentation changes
• Developer English proficiency: Most developers worldwide have working knowledge of English
• ROI diminishes: After Chinese, the benefit per language drops significantly

Arguments for additional languages:

• User experience: Native language documentation provides a better experience, particularly for beginners
• Market penetration: Could help adoption in regions with lower English proficiency
• Community building: Shows respect for diverse developer communities

So when thinking about translation for nicegui.io, we might want to focus on a 2-language solution. In contrast to supporting many languages, we could squeeze two languages into a docstring, for example, and let the @doc.demo() decorator pick the right one. This is just a rough idea and far from perfect though.

For two languages we could also further explore the idea of a second repository. What about some Git tooling that displays the diff of individual English pages since the corresponding Chinese page has been updates? I guess we could find a similar solution for docstrings.

[evnchn]

@falkoschindler Are you fine with having special tags (like hashtags) in the docstring?

If so, we can have a tag (Think: #translation_qwkfvnkslkd) which indicates to the website, hey if about to display this string, check the translation list id qwkfvnkslkd to see if there are other languages version.

Meanwhile, about #4530, we can also have such tags (Think: #group_binding, for those methods related to binding), then we can group the methods in an orderly manner in the website.

Otherwise, I totally don't see how to work around the fact that NiceGUI uses docstring. A string is a string, and it can only do so much...

[Yuerchu]

I noticed an issue with links generated from the reST documentation of elements. When I force-edit the documents to Chinese, the link target doesn't get added correctly. I initially considered using special tags, but ultimately concluded this wouldn't be a viable solution.

For example, the URL should be nicegui.cn/documentation/概览_overview but it becomes nicegui.cn/documentation#___overview.

[evnchn]

what have you done to do the force-edit?

[v479038280]

In fact, the translation effect of AI now is already better than that of most people, and I don't know if there is a need to translate it yet

[evnchn]

Not all AIs are so good, and not everyone has access to good AIs.

The Samsung one is... less than ideal.

Moreover not all AI models have the context. So perhaps a translation done on our side with a customized prompt is better.

[evnchn]

Also I'll say: I have to work on a project which needs chinese and english translation, for which they don't allow me to work on the project until June, therefore I'm contributing to NiceGUI's i18n in the meantime, and backporting the changes to my project later. 🧠

[falkoschindler]

After thinking about a translation management system for humans, automatic text extraction and AI-based translation:

What if we auto-generate an AI-based translation every time we deploy a new release? We could checkout the repository and ask an AI agent to translate every docstring and every text snippet of the documentation. Additional instructions could give context and steer the agent towards the desired result. It might not be perfect, but requires much less maintenance in the long run.

[evnchn]

Concerns:

• The translation of the same chunk of text must NOT change.
• The translation of a chunk of text which has gotten a minor addition should ideally NOT change anymore than needed.
• We need human-in-the-loop. We are NOT shipping translations to prod without at least someone looking at them, or making manual edits.

My idea so far:

• Intercept the doc.demo functionality for automatic text extraction.
• Generate a JSON of all strings and their machine translations.
• Allow for manual editing of the extracted strings.
• Implement a check for new machine translations:
  • Pair existing strings that haven't changed between translation attempts.
  • Identify the remaining strings with the least edit distance.
  • Include these identified strings in the LLM's context along with existing instructions.
• Leave the demo code alone.
  • If we have a different set of code for different languages, it may make debugging a broken demo to be way harder.
  • MultilingualString can't work for that, since it would show up in the source code, which is ugly and unwanted.

[Yuerchu]

After thinking about a translation management system for humans, automatic text extraction and AI-based translation:

What if we auto-generate an AI-based translation every time we deploy a new release? We could checkout the repository and ask an AI agent to translate every docstring and every text snippet of the documentation. Additional instructions could give context and steer the agent towards the desired result. It might not be perfect, but requires much less maintenance in the long run.

I maintain a relatively conservative stance towards AI.
Since AI translation cannot guarantee 100% accuracy, if AI generates incorrect translations, it may lead to unpredictable content, causing developers to write erroneous code.

• If AI must be used, I believe human review is required;
• Avoid using AI. Display documentation in the corresponding language if contributors have provided translations, and fall back to English if none are available.

[evnchn]

If AI must be used, I believe human review is required;

Yes. Human-in-the-loop, that's what they call in the lingo.

Avoid using AI. Display documentation in the corresponding language if contributors have provided translations, and fall back to English if none are available.

Prefer show AI translation with a disclaimer, than to not use AI out-right. There probably won't be a lot of contributors for translation, so yeah.