search

swiftlang / swift-docc

Documentation compiler that produces rich API reference documentation and interactive tutorials for your Swift framework or package.
https://swift.org/documentation/docc
Apache License 2.0
1.15k stars 120 forks source link

Internationalization support #648

Open pepicrft opened 1 year ago

pepicrft commented 1 year ago

Feature Name

Internationalization support

Description

It'd be great if Swift DocC supported internationalization like other documentation-generation tools do:

Swift DocC can establish a convention of how Markdown pages in multiple languages are structured in the file-system, generate an HTML page per language so that they can be indexed by search engines, and add a language switcher so that developers can easily switch between languages.

Motivation

While it's not common for API documentation to be translated, it's common to see documentation in longer form like tutorials to be translated for audiences that are not comfortable working in English. By supporting this feature we'd motivate Swift Package developers to translate their documentation removing language barriers from their packages.

Importance

It makes packages' documentation more accessible by eliminating language barriers.

Alternatives Considered

The alternatives that I considered are using the aforementioned documentation generators, but I'd like to use Swift DocC so that it's more tightly integrated into developers' workflows and tools.

d-ronnqvist commented 7 months ago

This is a pretty big feature with a lot of open questions about its potential design and authoring experience.

pepicrft commented 7 months ago

@d-ronnqvist is there a process to kick off those discussions. I'd be happy to take the lead there is external contributions are allowed. We are a happy user of Swift DocC and would love to see this need being addressed.

d-ronnqvist commented 7 months ago

There isn't really a formal process for this but a good first step would be to start a thread in the Swift Forums with the goal of uncovering different use cases and workflows. The initial post doesn't have to be long or complicated. It mainly needs to contain a brief (maybe single paragraph) introduction of the topic, some examples of the type of content that you are looking to translate, and a call to action for other people to chime in with examples of the type of content that they would be interested in translating.

The goal at this point is to gather information to know what questions to ask and what specific problems we're looking to solve. In addition to what content people are looking to translate, it'd also be good to try and get some sense of people's translation workflows to learn more about what DocC needs to offer as a tool to fit in well with these workflows.

Once that forums thread has gathered a good list of use cases and workflows it's time to shift the conversation towards defining problems to be solves and proposing a high level design to solve them. Depending on how long the tread has gotten it may be better to start a new thread and summarize the conclusions from the previous thread to make it easier for new people to join that discussion if they weren't also part of the use cases discussion.

pepicrft commented 7 months ago

Thanks a lot @d-ronnqvist for the detailed response. I'll start a discussion on Monday.