Welcome, world.
“Astro is for everyone” is a common saying on our team. It began as a saying to help us design APIs and relate to our users. But as Astro has evolved, this core value of accessibility has worked its way into more than just feature development.
Astro is for everyone
If Astro is truly meant to be for everyone, then you must include the majority of the planet (83%) that does not speak English! 18 months ago, we decided to get serious and invest in overhauling our documentation, and this included a major internationalization (i18n) initiative.
Today, Astro docs has been officially translated into 12 different languages with over 1000 pages translated in total. Even our full introductory tutorial (32 pages in total) has been translated into six different languages. These languages cover billions of people across more than 50 countries, opening the door to many who would otherwise struggle to use Astro reliably.
Our translations are almost entirely made up of open-source contributions, submitted by volunteers all over the world. We are so, so grateful to everyone who has contributed so far.
Today is our official Community Day celebration, so we wanted to share how we built this internationalization engine at Astro. We are lucky to have one of the best communities in open-source, and wanted to share some of our successes — and challenges — with you in this post.
Recognizing Non-Code Contributions
Often, open-source projects focus too heavily on code contributions (issues, pull requests, bug fixes, new features) and ignore other forms of support. One of the most important, early decisions that we made with Astro was to change this, and to specifically call out and recognize non-code contributions from day one.
This was explicitly written into our GOVERNANCE.md document, which stated that someone could become a maintainer of Astro by any measure and form of contribution, not just lines of code.
Today, some of our best new maintainers get their start through non-code contributions:
- Documentation
- Translations
- Support
- Community-building and advocacy
Contributor Onboarding
Successfully completing your very first open-source contribution is sometimes the hardest part. With that in mind, we carefully constructed our i18n contributors’ journey with as little friction and barriers to entry as possible.
Not all potential contributors will be familiar with GitHub’s workflow involving git, branching, merge conflicts, etc. It might seem like an odd choice to throw non-code contributors into such a code-heavy environment. However, with our code stored on GitHub, we can keep our content on an open platform, while also keeping the translated content close to the code of the docs site itself.
This means every contributor, for every kind of contribution, uses the same platform and has the same contributing experience. Instead of thinking of internationalization as some “other” thing, it’s a part of documentation. Our list of open PRs includes translations along with content updates and site infrastructure code fixes.
To help people feel comfortable jumping in, and give them some clear direction on how to get started, we created a full Translation Guide in addition to our regular CONTRIBUTING.md. This contains not only the technical details about how our translations work but is also full of advice and tips for any beginner who might feel overwhelmed at the prospect of contributing.
Communication
Our translators are not only fully integrated into our “docs as code” process, but also wider community discussions, and decision-making.
Our translators coordinate and conspire on the Astro Discord server in their own #docs-i18n channel and dedicated language-specific threads. It’s a special place where they are free to speak in (or about) their own language as they work on translations.
At the same time, our translators are an active, engaged part of the wider Astro community and discussion, participating in general or off-topic conversations. You’ll also often find them in more specific channels such as #dev or #docs, where thanks to their participation, we are able to deliver several internationalization improvements to both our docs and our core product from their feedback.
And of course, you’ll also find them dropping docs links and answering questions in our #support threads because they know the docs so well from having translated them!
Automation and Tooling
It’s one thing to know how to get started. But, translators also need to know where to get started!
Led by beloved Astro maintainer Hippo, our docs team built a custom Translation Tracker, the showpiece of our i18n automation! It tracks every docs page marked as “available to translate” by language and reports its own current state:
- fully-translated and up-to-date;
- needing an update to match the English documentation;
- or, not yet translated.
Internally, it uses the git history to compare changes between languages, defines the status of each page through some checks, and also generates a GitHub link with all the commits a page needs to be in sync with the English version. It’s powered by GitHub Actions, right out of our docs repo.
Our Translation Tracker also uses GitHub data to list open translation PRs in need of reviews from native speakers, which are a great way to get started without the pressure of opening your own PR!
With a clear picture of what our translation needs are, we are able to quickly welcome and onboard new i18n contributors who already know which contributions are wanted.
Driving decisions through data
Initially, we made translation decisions (e.g. which languages to support in docs) based solely on our community’s excitement and availability to help us. This proved to be a good strategy when we were just getting started. But as Astro docs grew, we needed to make more informed decisions.
One of the difficult calls we had to make early on was to decide which languages we would officially support with translations. Or rather, which ones we would not. Officially supporting a language is quite a large commitment, which unfortunately means that we cannot accept every language proposed to us. Our goal was to find a balance between languages easier for us to maintain and the ones that would make the most impact. Access to quality information and education isn’t the same everywhere — and as the ones with the privilege of English proficiency ourselves, we are in a position of strength to address these inequities and advocate for the communities who need translations the most.
To help us make these difficult decisions, we analyzed several data points such as the number of members for each language in our Discord, a list of countries per language, demographics of several developer surveys, and EF’s English Proficiency Index. By starting with clear goals, we could choose languages that helped keep us focused on meeting the needs of the global developer community.
Supporting our contributors
The last couple of months in particular have been focused on supporting and recognizing the massive work done by our internationalization teams. While Astro Docs has long had a “Face Pile” of the GitHub avatars of every contributor to the repository, we now display a dedicated translators’ face pile on each translated version of the site. Our popular community Astro Badges also now displays unique i18n contributions to acknowledge both translations and translation reviews.
Thanks to the Astro open-source project having so many generous sponsors and backers, we are able to issue regular monetary Community Awards. At the time of posting, we have already given more than $4000 Open Collective funds directly to our international community. Other forms of rewards include limited edition swag items from the Astro Swag Shop (all proceeds go directly back into our Open Collective), stipends, and sponsorships.
Going forward
We’re thrilled with the results of our intentional focus on the internationalization (i18n) of our documentation, and so humbled and gratified by the enthusiasm and appreciation we’ve received. We know that the success of any open-source project depends on supporting every member of your community.
This is just the beginning, and we’re super excited to share more about our internationalization story with the wider open-source community! In particular, we hope to generalize and package our home-grown tools such as our Translation Tracker so that they can be used by other open-source projects. So stay tuned, and join us, as we build a new era for open-source internationalization!