Add Typst docs translations?

[jcbhmr]

EXISTING PROJECT: https://github.com/typst-doc-cn
https://typst-doc-cn.github.io/docs/
by @Parsifa1 @OrangeX4 @Enter-tainer (i think)

@typst-community and @typst-doc-cn are both community-driven "extending the @typst project" ideas. 🤷‍♂️

also it might help to get other eyes on the translations if they're all in one spot instead of one project for chinese translations, one for spanish, and one for french, and one for german, etc. all spread across different repos/orgs vs all in one spot. 🤔

demo idea of how a single site might have multiple translations (ignore broken links and such): https://github.com/jcbhmr/typst-docs/tree/c7f2498be9f43865d55da5564479cf9f9302b162 https://jcbhmr.me/typst-docs/ HAS CHANGED
_{(yeah its a completely new site thingie; but VitePress has above-average internationalization capabilities when compared to other static site generators!)}

[OrangeX4]

I believe a unified documentation website is indeed necessary, but I think this unity should be provided by the typst official rather than establishing another unified unofficial translation website. Currently, the official documentation is maintained through doc comments, and the existing unofficial Chinese translation websites are patched based on these doc comments. Your Markdown-based website may become difficult to maintain, especially in the reference section. This is the concern I have.

[huwaireb]

I fully agree, however

There is a huge difference between official and unofficial documentation, usually the community would love to have a place to articulate resources relating to Typst that the official typst team wouldn't have time to maintain. As such, it would be ideal for a community org to pursue.

In your case, yes you are doing god's work translating official documentation so it should be pushed for Typst's official website to gain i18n support. but if at any point you go any further through custom resources it may be better to pursue a merger of some sort.

as long as you guys agree of course!

ops: i thought this was another discussion ;c, still vaguely applicable.

[OrangeX4]

Yes, I think merging is valuable. But I'm talking more about the technical difficulty here. At present, @jcbhmr has adopted a new solution to add a new website that uses markdown, but it is difficult for pure markdown to be consistent with the official documentation website, a simple example is https://typst.app/docs/reference/foundations/array/, how can a website based on markdown achieve the same result as this page?

[huwaireb]

@jcbhmr suggestion is by no means de facto, it's simply a suggestion.

The main problem is in the nature of how builtins are documented. If they truly are as doc comments, it would be generally ideal to move towards a different, maintainable & flexible approach. Not suggesting static markdown which would cause us to replicate every single entry from scratch, but instead perhaps something that would auto generate from typst files. As in a "typstdoc" similar to "rustdoc" and others.

builtins could be in .typ files that act as placeholders, never have to be in rust code

I see you extracted to .yaml files, good solution, should've been less complicated than what i'm suggesting here with a "typstdoc".

[OrangeX4]

Yes, so you should be able to understand what I mean, this work can only wait until Typst officially provides i18n support, and it is difficult for the community to do it.

Otherwise, it will be difficult for us to maintain it with the typst version upgrade. It's not difficult to build a documentation website, but it's the hardest thing to keep updating.

[OrangeX4]

But if there's any technical solution better, I think it's a good idea to merge them together.

[YDX-2147483647]

Maybe it's time to reconsider?

Well, a year passed and things changed.

• The way of reading and writing docs might change. (or might not)

  On the supply side, typst now supports exporting html. On the demand side, tinymist may also wants to localize docs and diagnostics in VS Code.

  • 2024-03-11 Tinymist published the initial release.

  • 2024-05-11 Tinymist started ng, and people have been discussing the possibility of localizing docs and error messages in VS Code internally from time to time.

  • 2024-11-05 https://github.com/nvarner/typst-lsp was archived and deprecated in favor of tinymist.

  • 2025-02-19 Typst 0.13.0 added experimental html export.

• Collecting info from crates/**/*.rs becomes easier.

  • 2024-02-27 The PR that adds basic typst-docs CLI that spits out JSON was merged.

  • 2024-10-08 https://github.com/typst-doc-cn/typst-doc-cn.github.io added a banner to remind that the translation might be outdated, and recommend Chinese FAQ.

  • 2025-03-14 https://github.com/typst-doc-cn/docs (typst-docs-l10n) was created. It allows localization in the following fashion.

    [reference.context.description]
    en = "How to deal with content that reacts to its location in the document.\n"
    zh = "如何处理对文档中位置做出反应的内容。\n"

• Web front ends capable of rendering the JSON have been developed.

  • 2025-02 https://github.com/JL710/typst-mdbook-docs was created. It convert the JSON to markdown, and builds a mdbook from it.

  • 2025-04-12 https://github.com/typst-jp/typst-jp.github.io added a whole new front end (Hono JSX / SSG) to the website.

  • 2025-07-27 (yesterday) I realized that website/ in typst-jp can be misused to preview typst.app/docs (of any PR) on netlify.

  • 2025-07-28 (today) https://github.com/3w36zj6 is considering making the SSG reusable for projects other than typst-jp. https://github.com/typst-jp/typst-jp.github.io/issues/233

  • 2025-08-19 https://github.com/Engage-Press/typst-docs Tool to build a local mirror of the typst documentation

A possible plan

(Suggested by others)

1. Build English PDF and put it into a CI
2. Build translated PDF
3. Build translated website.

Edit: The Documentation forge has been created on Discord.

Edit: https://github.com/Yourouchour/Typst-Automatic-Translation

[Andrew15-5]

I'm pretty sure things will start moving when docs will be moved to Typst. Which supposedly will happen in the near future? Since 0.14 is literally all about HTML and a11y. Then you don't have to rely on Markdown building tools and just use Typst with json() or whatever.

typst/typst#6417 (comment)

[Its-Just-Nans]

Adding some links :)

• https://github.com/Its-Just-Nans/typst.github.io
• https://typst-github-io.n4n5.dev/
• Make Typst Docs Entirely in Typst! typst/typst#6704
• https://github.com/typst-jp/typst-jp.github.io/issues/233
• https://discord.com/channels/1054443721975922748/1399326777540608041/1399331170289848360

[YDX-2147483647]

@Its-Just-Nans is working on making the website generator of https://typst-jp.github.io (Japanese translation of https://typst.app/docs, Apache-2.0 licensed) distributable (e.g., for multilingual/nightly docs).

He/she already has a proof of concept at https://github.com/Its-Just-Nans/typst.github.io.
Is it possible to create a new repo under this org?

Quoting from https://github.com/typst-jp/typst-jp.github.io/issues/233#issuecomment-3193719059:

I agree that having a repo under typst-community organisation would be great, and for example with a domains like docs.typst.community but for now typst.community looks 404

Update

Yes, we could possibly set that up, I can invite them later today
https://discord.com/channels/1054443721975922748/1194684809906237500/1406297976737108029

[3w36zj6]

Hi,

I'm one of the core maintainers of the Japanese community and the author of the SSG. Currently, with the help of @YDX-2147483647 and @Its-Just-Nans , we are working on separating the SSG from the Japanese documentation repository. Once this is complete, the SSG will likely be named something like typst-docs-web and will be much easier for others to use. Since this tool is not specific to the Japanese community, I believe it would be best for it to be managed by the global community.