Projects such as JAnim feature documentation in multiple languages. In JAnim's case there are two languages: Chinese and English.
Existing frameworks such as readthedocs and mdbook mainly use GNU gettext for i18n. While popular and stable, it is not the best choice for Otter Docs. gettext generates .po files, which requires the command line, plus, using it breaks the "no external tools" guarantee.
Since Typst already has support for various data structures, a somewhat usable solution might be something like this:
- The smallest translatable unit is the page, or chapter.
- Make a helper that reads each chapter and evaluate them, then use repr to convert the result to a string
- That string is then hashed (i.e. digestify).
- Each translation would include that hash, and if the hash doesn't match, emit a warning.
That, however, leads to synchronization problems. Using eval then repr avoids formatters and whitespace-only changes from changing the hash, however it is impossible to inspect the stuff inside context when compiling. Translators won't know if the author changes some HTML specific stuff. Luckily this doesn't affect compilation (it's synchronization stuff), handles external files well, and doesn't introduce foreign tools. But the granularity is quite bad. Translators may want to translate content paragraph by paragraph instead of page by page, and it doesn't integrate well with existing translation platforms such as Crowdin.
Projects such as JAnim feature documentation in multiple languages. In JAnim's case there are two languages: Chinese and English.
Existing frameworks such as readthedocs and mdbook mainly use GNU gettext for i18n. While popular and stable, it is not the best choice for Otter Docs. gettext generates .po files, which requires the command line, plus, using it breaks the "no external tools" guarantee.
Since Typst already has support for various data structures, a somewhat usable solution might be something like this:
That, however, leads to synchronization problems. Using eval then repr avoids formatters and whitespace-only changes from changing the hash, however it is impossible to inspect the stuff inside
contextwhen compiling. Translators won't know if the author changes some HTML specific stuff. Luckily this doesn't affect compilation (it's synchronization stuff), handles external files well, and doesn't introduce foreign tools. But the granularity is quite bad. Translators may want to translate content paragraph by paragraph instead of page by page, and it doesn't integrate well with existing translation platforms such as Crowdin.