gh-156360: Improve turtle translation support

[StanFromIreland]

• Issue: Set up a coordinated system for the translation of turtle's docstrings #156360

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34776456 | 📁 Comparing 17b86a7 against main (9036982)

  🔍 Preview build  

397 files changed · + 8 added · ± 389 modified

+ Added

• builtins/constants.html
• builtins/exceptions.html
• builtins/functions.html
• builtins/index.html
• builtins/stdtypes.html
• builtins/threadsafety.html
• builtins/time-complexity.html
• library/tkinter.dialogs.html

± Modified

• glossary.html
• index.html
• license.html
• py-modindex.html
• c-api/arg.html
• c-api/bool.html
• c-api/buffer.html
• c-api/bytearray.html
• c-api/bytes.html
• c-api/capsule.html
• and 379 more...

[StanFromIreland]

@m-aciek can you please take a look?

[m-aciek]

After thinking it through, I don’t think we need to change the existing loader. The turtle-translations package can provide modules such as turtle_docstringdict_pl.py containing a docsdict dictionary, which older Python versions can already load through turtle.cfg. This would let us distribute and update translations independently of Python releases while preserving compatibility with the existing loading mechanism.

Documenting the package would still help users discover and install translations, and an environment variable for selecting the language could be a convenient addition. Could we focus this PR on those improvements and keep the existing loader?

[StanFromIreland]

I'm still not convinced, however, for two reasons:

• it's namespace clutter, which isn't ideal, especially when we'll have quite a few translations.
• unless we release translations specifically for older versions, they won't load.

[m-aciek]

I agree that the top-level modules introduce some namespace clutter; that seems to be the main trade-off of preserving compatibility with the existing loader.

For the version-compatibility issue, though, I don't think this necessarily requires separate releases of turtle-translations for older Python versions. A single release could ship version-specific docsdict data and have the turtle_docstringdict_<lang> modules select the appropriate one based on sys.version_info.

The version-specific dictionaries could also be generated from the common translation catalogue against the API exposed by each supported turtle version, so entries for newer methods simply wouldn't be present when loaded by an older Python.

[StanFromIreland]

Ok, let's try that for now, and we can always iterate since there's quite a bit of time till the feature freeze. I've made the switch, please review.

[m-aciek]

Thanks for the update. Could we make the documentation easier to follow for beginners by leading with a complete example of enabling a translation, followed by a link to instructions for contributing a new language? The dictionary format and module lookup details could go alongside write_docstringdict().

In the introduction, “translations” would be clearer than “translation catalogues” or “docstring dictionaries”. It would also help to explain that only the help text is translated; Python function names remain unchanged.

[StanFromIreland]

I reshuffled some things around, thanks for the review.

I'd like to wait a little before we start deprecating things, and I need to think a bit more about what to do with the eval.

[m-aciek]

🚀 I left yet couple of non-blocking suggestions.