open-feature
Localization support for OpenFeature documentation
Hi, OpenFeature team! 👋🏼
Documentation is the backbone of any project, and it’s often the first touchpoint for new contributors and adopters. Having docs available in multiple languages lowers the entry barrier, makes the project more inclusive, and helps adoption in regions where English isn’t the primary language.
As an active contributor to the OpenTelemetry project for over a year, I’ve seen how impactful this process can be. OpenTelemetry now supports several localizations on its docs, which has made it easier for contributors and users in those communities to participate and learn more about the project.
Since I couldn't find any guidance regarding localization in the OpenFeature docs, I'm opening this issue that could serve as a starting point for discussion. The main proposals are:
- Explore whether the project is open to supporting multiple languages.
- If so, add localization support to the OpenFeature documentation.
- Start with the Portuguese localization as a pilot, with potential contributors, and expand gradually.
Hey @vitorvasc, thanks for kicking this off. I have some questions about how internationalization would work, but I'd be happy to support you if you're interested in piloting adding support for Portuguese.
- What happens when a page hasn't been translated to the selected language?
- How does OTel translate new content? I'm assuming contributions typically start in English and GitHub issues are created as a follow-up.
- What type of content should be translated? The code itself (and comments) are all English, so we would focus on the main marketing page and concept sections only?
- Have you used the internationalization option in Docusaurus? This may require us to update our Alogia configuration to be language aware.
I think a prototype would help answer a lot of those questions. Is this something you'd be willing to work on @vitorvasc? Thanks!
Hi @beeme1mr! I'm glad to hear this is something the OpenFeature team could support. Let me share more details from my OTel experience by addressing the topics:
- What happens when a page hasn't been translated to the selected language?
In the OTel docs, we have a fallback mechanism. If you select a language and open a page that hasn't been translated yet, it defaults to the English version and displays a banner indicating that the page hasn't been translated. In addition, there's a Google Translate widget that allows you to translate that page.
Example: https://opentelemetry.io/pt/docs/platforms/ - The Google Translate widget is on the left side, at the top of the sidebar.
That said, the translations provided by Google Translate aren’t always fully accurate. Sometimes it may mistranslate technical terms or even alter the context, so it’s not a replacement for a proper localization team 😅
- How does OTel translate new content? I'm assuming contributions typically start in English and GitHub issues are created as a follow-up.
That's correct, contributions always start in English. Each localization team has it's own SIG, which allows them to decide whether to prioritize translating newly added content or catching up on older, untranslated pages.
The same approach applies to updating drifted content. As docs approvers/maintainers, we regularly check how many pages are drifted in each locale. If we see more than 20 drifted pages (a magic number that we commonly agreed), we open an issue and assign it to the respective SIG, asking them to update the content.
For example, in the Portuguese locale you can filter the issues using the lang:pt label.
- What type of content should be translated? The code itself (and comments) are all English, so we would focus on the main marketing page and concept sections only?
That's a good one. In general, we have this Localization guidelines that standardizes what can and cannot be translated.
For example, the code itself is never translated. Comments and diagrams are optional, but in Portuguese we often translate them. Each locale can decide whether to translate these elements or not.
In the Portuguese locale specifically, we don't translate component names such as Tracer Provider or Collector. Some other English terms like issues (when referring to GitHub Issues) are also kept in English, since that's how they're commonly used. On the other hand, we do translate concept terms like Metrics, Traces and Spans.
Here's an example from the SDK -> Go page in Portuguese.
- Have you used the internationalization option in Docusaurus? This may require us to update our Alogia configuration to be language aware. I think a prototype would help answer a lot of those questions. Is this something you'd be willing to work on @vitorvasc? Thanks!
I have never used Docusaurus at all 😄 but I'd be happy to read the documentation, learn more about it, and even explore how to set up - similar to what I did with the Hugo framework on OTel.
I'd also be glad to work on a prototype; I'm really interested in this. Just let me know how we can get started!
Hey @vitorvasc, that all sounds great. I'd recommend forking the repo and running it locally. From what I can tell, adding basic support in Docusaurus should be fairly straightforward. We should also consider internationalizing the main marketing page, which takes advantage of the React support in Docusaurus. Feel free to open a PR, even if it's a draft, and we can work through the details together. Thanks again for offering to help.
@beeme1mr Great!
I'll start working on the initial setup, including the homepage internationalization and get back to you when I have the PR ready.
Let me know if there's anything else you'd like me to keep in mind. Thanks!