From 8b61a18afdd3a5cfdd5775fcc699cf6ef799a957 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Thu, 15 Jun 2023 17:07:24 +0200 Subject: Add translation contribution docs (#215) Co-authored-by: Sarah Rainsberger --- CONTRIBUTING.md | 27 ++++++++++++++++++++++++++- packages/starlight/translations/README.md | 14 ++++++++++++++ 2 files changed, 40 insertions(+), 1 deletion(-) create mode 100644 packages/starlight/translations/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 300fa58e..47d00dd7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,6 +30,8 @@ We encourage you to: - [**Review existing PRs**][pulls] to help us merge contributions sooner. +- [**Add or update translations**](#translations). We need help translating both Starlight’s UI and documentation. + ## About this repo This repo is a “monorepo,” meaning it contains several projects in one. It contains the Starlight docs site in [`docs/`](./docs/) and the packages that make up Starlight in [`packages/`](./packages/). @@ -87,7 +89,30 @@ pnpm dev You should then be able to open and see your changes. -### Understanding Starlight +## Translations + +Translations help make Starlight accessible to more people. + +### Translating Starlight’s UI + +Starlight’s UI comes with some built-in text elements. For example, the table of contents on a Starlight page has a heading of “On this page” and the theme picker shows “Light”, “Dark”, and “Auto” labels. Starlight aims to provide these in as many languages as possible. + +Help out by adding or updating translation files in [`packages/starlight/translations`](./packages/starlight/translations/). +Each language’s JSON file follows the [translation structure described in Starlight’s docs](https://starlight.astro.build/guides/i18n/#translate-starlights-ui). + +### Translating Starlight’s docs + +Starlight’s documentation is also translated into multiple languages. You can find the source code for the site in [the `docs/` directory](./docs/) of this repository. + +Help out by: + +- Reviewing [open translation PRs][pulls] +- Updating out-of-date translated pages +- Adding an untranslated page + +Visit **** to track translation progress for the currently supported languages. + +## Understanding Starlight - Starlight is built as an Astro integration. Read the [Astro Integration API docs][api-docs] to learn more about how integrations work. diff --git a/packages/starlight/translations/README.md b/packages/starlight/translations/README.md new file mode 100644 index 00000000..f3d02b34 --- /dev/null +++ b/packages/starlight/translations/README.md @@ -0,0 +1,14 @@ +# Starlight UI translation files + +This directory contains translation data for Starlight’s UI. +Each language has its own JSON file and follows the [translation structure described in Starlight’s docs](https://starlight.astro.build/guides/i18n/#translate-starlights-ui). + +## Add a new language + +1. Create a JSON file named using the BCP-47 tag for the language, e.g. `en.json` or `ja.json`. + +2. Fill the file with translations for each UI string. You can base your translations on [`en.json`](./en.json). Translate only the values, leaving the keys in English (e.g. `"search.label": "Buscar"`). + +3. Import your file in [`index.ts`](./index.ts) and add your language to the `Object.entries`. + +4. Open a pull request on GitHub to add your file to Starlight! -- cgit