Support for Multilingual Documentation in dartdoc

[naghinezhad]

Feature Request: Multilingual Documentation Support

I would like to request a feature that enables multilingual support for documentation generated by dartdoc. Currently, dartdoc generates documentation in a single language, but many developers work on projects that require support for multiple languages.

Use Case:
For example, I have a Dart project where the primary documentation is in English, but I want to provide translations in Persian (Farsi) and other languages for a broader audience.

Suggested Implementation:

1. Adding support for localization files (such as .arb, .json, or other formats) to store translated strings.
2. Providing an option in dartdoc_options.yaml to specify available languages.
3. Generating language-specific documentation in separate folders (e.g., docs/en/, docs/fa/).
4. Including a language switcher in the generated HTML output.

This feature would greatly enhance the usability of dartdoc for international projects.
Would this be possible to implement? I appreciate any feedback on this idea!

[srawlins]

This would be possible to implement, but would be a large effort.

[jonasfj]

My two cents is that this isn't something we should implement.

If you want to translate documentation you are probably better off writing the documentation outside source code comments.

There is no pretty way to do that today, but you could use {@tool ...} annotations to do it.

See: https://pub.dev/packages/dartdoc#tools

---

You could do:

/// {@tool translate}
/// Documentation comment for [Foo] class.
/// {@end-tool}
class Foo {}

Then you define a translate tool in dartdoc_options.yaml. The translate tool gets the data between {@tool translate} and {@end-tool} and translates it by looking up some .arb files (or similar).

You can probably even hack a translate tool that tracks which invocations it doesn't have translations for and adds them to the .arb file.

You'd then have to run dartdoc for each language you want to produce docs for, and either hard code the language in the translate tool, or in tool configuration in dartdoc_options.yaml.
In an ideal world, we'd allow some environment variables to passed through from invocation of dartdoc to invocation of tools, such that this could simply be MY_TRANSLATE_TOOL_LANG=en dartdoc -o doc/api/en/.

I'm not saying this will work fantastically, but it can be made to work.

Warning

{@tool ...} invocations are disabled on pub.dev, so if you want pretty documentation there, this trick won't work. Maybe, in some future we can allow tool invocations on pub.dev, but that's not right now.

[jonasfj]

@szakarias I think we should close this as out-of-scope, and decide that if someone really really wants to translate documentation then they should:

• (A) Leverage {@tool ...} annotations to inject translations from external sources.
• (B) Run dartdoc once for each language and manage the folder structure themselves.

My personal opinion is that translating reference documentation is probably overkill. More likely it'll lead to outdated and inconsistent documentation in some languages. In my personal opinion users who really want to translate documentation for their package, should focus on writing tutorial-style documentation, and translate the tutorials.