Skip to content

Commit 4c1da63

Browse files
yanthomasdevyanthomasdev
authored
Merge branch 'main' into yan/a11y-sprinkles
2 parents dc364db + a1f218a commit 4c1da63

47 files changed

Lines changed: 1039 additions & 225 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎MAINTAINERS.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,33 @@ For PRs that are translations to existing Docs content, including new page addit
9393
- If you speak the language natively, check the content for accuracy. Note: some languages have created their own glossaries and/or language guides located in their language folder within `/src/i18n/`.
9494
- If you do not speak the language natively, and the PR has not had any recent activity, you can use online translation tools (e.g. Google Translate) and scan the results for anything that looks wildly out of place. Also, visit the page in the PR’s Netlify deploy preview to verify that nothing is visually out of place. While we always prefer to have a review from a native speaker of the language, having translated docs with some errors is usually better than having no docs at all.
9595

96+
#### Correcting an Incorrect Translation Status
97+
98+
If the Translation Status Overview Issue incorrectly shows "needs updating" for a page (e.g. a typo fix to an English page triggered the status update), take the following steps to manually update the tracker:
99+
100+
- Open the [Translation Status Overview](https://github.com/withastro/docs/issues/438) Issue.
101+
- Click the "Edit" button.
102+
- Find the big JSON object at the end (i.e. the translation's internal progress data).
103+
- Replace the `lastMajorChange` value of the affected languages with today's date and hour.
104+
105+
The JSON object will look something like this:
106+
```json
107+
{
108+
"zh-cn": {
109+
"comparing-astro-vs-other-tools.md": {
110+
"lastChange": "2022-07-27T19:08:40.000Z",
111+
"lastCommitMsg": "Core Concepts PR follow-up (#1126)",
112+
// This property below is the one you should change!
113+
"lastMajorChange": "2022-07-27T19:08:40.000Z",
114+
"lastMajorCommitMsg": "Core Concepts PR follow-up (#1126)"
115+
},
116+
// (other pages...)
117+
}
118+
// (other languages...)
119+
}
120+
```
121+
122+
This process tells the tracker that the page was updated "now". The next time a PR gets merged, the translation tracking script will be rerun and the page will appear to have been updated, removing its "needs updating" icon.
96123

97124
## Submitting your own PRs
98125

‎TRANSLATING.md‎

Lines changed: 89 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -4,24 +4,31 @@ Thanks for your interest in helping us translate [docs.astro.build](https://docs
44

55
## Getting involved
66

7-
### How can I help translate one of the supported languages?
8-
Translations all live in this GitHub repository. You can add and update them by creating a pull request. Read on to find out more!
7+
To get involved in our translation efforts, we **highly recommend** [joining our Discord chat](https://astro.build/chat) first. This way, we can get you up to speed with our process and give you the opportunity to chat with your language's translation team.
98

10-
### How can I find out what needs translating?
11-
See our automated [Translation Status Overview issue](https://github.com/withastro/docs/issues/438) for a quick list of which pages are missing or need updating.
9+
Most of our internationalization decisions and discussions happen on Discord. Joining us there is the best way to find out which patterns and recommendations your language's translation team follows before making your own PRs. You can even become a part of the decision-making process.
1210

11+
> Can’t access Discord? Please [open a new issue](https://github.com/withastro/docs/issues/new/choose) here on GitHub to ask any questions you may have.
12+
13+
### How can I help translate/review one of the supported languages?
14+
15+
Translations all live in this GitHub repository. You can add and update them by creating a pull request or reviewing pending translations in the "Pull Requests" tab. Read on to find out more!
16+
17+
### How can I find out what needs to be reviewed/translated?
18+
19+
To find translations pending review, you can filter through this repo's [Pull Requests with the i18n label](https://github.com/withastro/docs/pulls?q=is%3Apr+is%3Aopen+label%3Ai18n).
20+
21+
See our automated [Translation Status Overview issue](https://github.com/withastro/docs/issues/438) for a quick list of which pages are missing a translation or need updating to match a change to the English version.
1322

1423
> **Warning**
15-
> Please do not translate any pages without first checking their status in our [Overview Issue](https://github.com/withastro/docs/issues/438)!
24+
> Please do not translate any pages without first checking their status in our [Overview Issue](https://github.com/withastro/docs/issues/438)! If a page is not listed here as needing a translation or an update, we can not accept your PR.
1625
17-
Not every page is marked as "ready to translate." So, even if you find a page that is not yet translated on the Docs site, you must confirm that it is on the list of available pages to translate. If the `.md` files does not contain `i18nReady: true` in its YAML frontmatter, do not translate the document.
18-
19-
You can read more about how pages are marked "ready for (initial) translating" and "needs updating" in [CONTRIBUTING.md](https://github.com/withastro/docs/blob/main/CONTRIBUTING.md).
26+
Not every page is marked as "ready to translate." So, even if you find a page that is not yet translated on the Docs site, you must first confirm that it is on the list of available pages to translate. Do not translate documents that are missing:
2027

21-
### How can I participate in the conversation and decisions?
22-
Discussion around translation currently takes place in [the Astro Discord](https://astro.build/chat). Everyone is welcome to participate! If you are interested in getting involved, please reach out to us in the `#docs-i18n` channel.
28+
- A "Translate this page" button in the Docs site.
29+
- The `i18nReady: true` frontmatter property in its Markdown file.
2330

24-
> Can’t access Discord? Please [open a new issue](https://github.com/withastro/docs/issues/new/choose) here on GitHub to ask any questions you may have.
31+
You can read more about how pages are marked "ready for (initial) translating" and "needs updating" in [CONTRIBUTING.md](https://github.com/withastro/docs/blob/main/CONTRIBUTING.md).
2532

2633
## Languages for translation
2734

@@ -48,7 +55,7 @@ The official docs will only contain supported languages for now, but we will be
4855

4956
## Translation Structure
5057

51-
Generally speaking there are two kinds of content that we need to translate to internationalise the docs.
58+
Generally speaking, there are two kinds of content that we need to translate to internationalize the docs.
5259

5360
1. **Documentation pages** — explain how specific parts of Astro work
5461
2. **UI text** — used to structure and label the user interface of many different pages
@@ -91,50 +98,47 @@ If you spot something on [docs.astro.build](https://docs.astro.build/) that you
9198

9299
➤ Go to `src/pages/{language}/{page-slug}.md`
93100

94-
## Contributing to translations
101+
# Contributing to translations
95102

96103
Please see [CONTRIBUTING.md](https://github.com/withastro/docs/blob/main/CONTRIBUTING.md) for information about contributing via a fork, our Style Guide, and more!
97-
---
98104

99-
## Adding a new language
105+
## Review Tips
100106

101-
> 🛑 **Please don’t add a new language without first consulting with the docs team in [the `#docs-i18n` channel on Discord](https://astro.build/chat).**
107+
We love our reviewers! Reviewing PRs is an important task — it's thanks to the efforts of our reviewers that we can guarantee consistent, high-quality translations. Many projects track PRs that you submit, but we also celebrate review stats, visible on your very own [Astro Badge](https://astro.badg.es)! Visit our Discord and you'll see that we shout out every PR merged with a list contributors who helped with review comments.
102108

103-
### Prerequisites
109+
We even have an entire section in our Maintainer's Guide about [how to manually add reviewer's names to commit messages](https://github.com/withastro/docs/blob/main/MAINTAINERS.md#getting-co-authored-by-commit-message-name-and-email) before merging in case they are not automatically included!
104110

105-
To get started adding a language, you’ll need:
111+
So, if you're interested in helping review translation PRs, thank you! We really appreciate the effort, and we put an effort into showing it!
106112

107-
1. **Its BCP 47 tag**
113+
Learn more about [how to review and suggest changes](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) on GitHub Docs.
108114

109-
Examples: `en` / `pt-BR` / `ar`
110-
111-
This will be used for the HTML `lang` attribute and as the base for URLs for this language, e.g. `/{tag}/getting-started`. These tags can encode script-type and regions as well as language, but most often we will only need the language part unless we want to distinguish regional variants (as in the `pt-BR` example above).
112115

113-
#### Resources
114-
115-
- [Choosing a Language Tag](https://www.w3.org/International/questions/qa-choosing-language-tags) (in-depth guide)
116-
- [Subtag lookup web app](https://r12a.github.io/app-subtags/)
117-
- [IANA subtag registry](http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry)
116+
### Checklist
118117

119-
2. **Its name as written in the language**
118+
It can be confusing to know what exactly should be reviewed! Mostly, what we are looking for is another pair of eyes to catch any obvious mistakes. If that is all you do, you have been a HUGE help!
120119

121-
Examples: `English` / `Português do Brasil` / `العربية`
120+
Just ask yourself: does anything seem "out of place" or "unusual" when I read it? Are there typos or any unusual words choices that I would not expect to read? This might not mean the translation is "wrong" but *is* worth mentioning if a word choice is distracting when reading documentation.
122121

123-
This will be used to label this language in the site’s language switcher and potentially elsewhere. The best way to get this is probably to ask the person leading translation work for this language.
122+
If you want to take your reviews to the next level, here are some more questions you can ask yourself while reviewing translations:
124123

125-
### Scaffold files for a new language
124+
- Is the translation correctly written following the translated language's norms and practices?
125+
- Did the translation deviate from the original in a way that important information is being missed somehow?
126+
- Is the translation consistent with the language's style guide and glossary?
127+
- Are there any UI labels or content missing translation?
128+
- Are the custom components, asides, and code samples being properly displayed in the Deploy Preview?
129+
- Does the code samples' titles, syntax highlighting (like `js` or `astro`), and highlighted lines match the English version?
130+
- Are there any links that could be localized? (e.g. Wikipedia and MDN links)
126131

127-
To scaffold the basic files for a new language, use the `add-language` script from your terminal:
132+
**When you think a PR is good to be merged**, approve the PR through GitHub's "Review Changes" button or leave a "**LGTM!**" in the comments. (“LGTM” is an abbreviation of “Looks Good to Me” often used to approve pull requests.)
128133

129-
```bash
130-
pnpm run add-language
131-
```
134+
## Translation Tips
132135

133-
The CLI will prompt you for a tag and name for the new language as described above. Follow the instructions and the wizard will create a basic set of files to get started translating that language.
136+
### Language-specific Guides (Glossary & Style Guide)
134137

135-
Update the placeholder content in the newly created files, commit them, and away you go!
138+
Translators are free to create and mantain a glossary, style guide and other tips for their language's translation squad. This is a great way to keep translations consistent across contributors and to centralize team decisions. You can find it (or create it) inside the language's `i18n` folder as a `README.md` file.
139+
140+
Feel free to take a look at the [Deutsch Guide](https://github.com/withastro/docs/blob/main/src/i18n/de/README.md) for an example.
136141

137-
## Translation Tips
138142

139143
### Frontmatter
140144

@@ -173,6 +177,13 @@ i18nReady: true
173177
// Rest of the file's content is here...
174178
```
175179

180+
181+
### Code Samples
182+
183+
We have lots of code samples throughout our docs, and although we **recommend translating comments**, as they give a contextual clue of what's happening in the code, each language is **free to decide** whether or not they want to translate titles, variables, string values, function names, etc.
184+
185+
Be aware that if code samples are being translated, you may need to update some of the code sample's highlighted lines. Read the [Code Samples section](https://github.com/withastro/docs/blob/main/WRITING.md#code-samples) in our Writing Guide to know more about our syntax.
186+
176187
### Asides
177188

178189
Most of our pages include stylish tip/note/caution blocks called "asides". We use a custom syntax to author them which includes the type of aside (all lowercase) and optionally a custom title in square brackets. Here is an example of a "tip" found in the docs:
@@ -212,7 +223,7 @@ Astro allows us to import and include custom components in our Markdown pages. T
212223
</IslandsDiagram>
213224
```
214225
215-
**Do translate**: slotted content (content between opening and closing tags).
226+
**Do translate**: slotted content (content between the opening and closing tags).
216227
217228
**Do not translate**: import statements in the frontmatter, component names, and slot names (like `slot="headerApp"`)
218229
@@ -240,3 +251,42 @@ Some of our English page content is generated from outside sources, and must not
240251
However, these pages are translated directly here and **these warnings are not meant for translations**.
241252
242253
For these generated pages (like `configuration-reference.md`), we recommend **ignoring and removing the note and component (including its import) from the file**, thus avoiding confusion for other translators thinking that this warning applies to translations as well.
254+
255+
256+
## Adding a new language
257+
258+
> 🛑 **Please don’t add a new language without first consulting with the docs team in [the `#docs-i18n` channel on Discord](https://astro.build/chat).**
259+
260+
### Prerequisites
261+
262+
To get started adding a language, you’ll need:
263+
264+
1. **Its BCP 47 tag**
265+
266+
Examples: `en` / `pt-BR` / `ar`
267+
268+
This will be used for the HTML `lang` attribute and as the base for URLs for this language, e.g. `/{tag}/getting-started`. These tags can encode script-type and regions as well as language, but most often we will only need the language part unless we want to distinguish regional variants (as in the `pt-BR` example above).
269+
270+
#### Resources
271+
272+
- [Choosing a Language Tag](https://www.w3.org/International/questions/qa-choosing-language-tags) (in-depth guide)
273+
- [Subtag lookup web app](https://r12a.github.io/app-subtags/)
274+
- [IANA subtag registry](http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry)
275+
276+
2. **Its name as written in the language**
277+
278+
Examples: `English` / `Português do Brasil` / `العربية`
279+
280+
This will be used to label this language in the site’s language switcher and potentially elsewhere. The best way to get this is probably to ask the person leading translation work for this language.
281+
282+
### Scaffold files for a new language
283+
284+
To scaffold the basic files for a new language, use the `add-language` script from your terminal:
285+
286+
```bash
287+
pnpm run add-language
288+
```
289+
290+
The CLI will prompt you for a tag and name for the new language as described above. Follow the instructions and the wizard will create a basic set of files to get started translating that language.
291+
292+
Update the placeholder content in the newly created files, commit them, and away you go!

‎public/index.css‎

Lines changed: 12 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -483,16 +483,14 @@ button {
483483
}
484484

485485
h2.heading {
486-
font-size: 1rem;
487-
font-weight: 700;
488-
text-transform: uppercase;
486+
font-size: 1em;
487+
font-weight: 600;
489488
margin-bottom: 0.5rem;
490489
margin-top: 1.5rem;
491490
}
492491

493492
.header-link {
494-
font-size: 1rem;
495-
padding: 0.1rem 0 0.1rem 0;
493+
font-size: 1em;
496494
transition: border-inline-start-color 100ms ease-out, background-color 200ms ease-out;
497495
}
498496

@@ -501,11 +499,19 @@ h2.heading {
501499
gap: 0.5em;
502500
width: 100%;
503501
font: inherit;
502+
padding: 0.4rem 0;
503+
line-height: 1.3;
504504
color: var(--theme-text-lighter);
505505
text-decoration: none;
506506
unicode-bidi: plaintext;
507507
}
508508

509+
@media (min-width: 50em) {
510+
.header-link a {
511+
padding: 0.275rem 0;
512+
}
513+
}
514+
509515
.header-link:hover,
510516
.header-link:focus,
511517
.header-link:focus-within {
@@ -524,17 +530,9 @@ h2.heading {
524530
opacity: 0.8;
525531
}
526532

527-
.header-link.depth-3 {
528-
padding-inline-start: 1rem;
529-
}
530-
.header-link.depth-4 {
531-
padding-inline-start: 2rem;
532-
}
533-
534533
/* Add line and padding on the left side */
535534
.header-link {
536535
padding-inline-start: 1rem;
537-
border-inline-start: 3px solid var(--theme-divider);
538536
}
539537
.header-link.depth-3 {
540538
padding-inline-start: 2rem;
@@ -550,7 +548,7 @@ h2.heading {
550548
}
551549

552550
.header-link {
553-
border-inline-start-width: 4px;
551+
border-inline-start: 4px solid var(--theme-divider);
554552
}
555553
}
556554

‎public/theme.css‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
:root {
55
--theme-navbar-height: 6rem;
66
--theme-mobile-toc-height: 4rem;
7-
--theme-left-sidebar-width: 20rem;
7+
--theme-left-sidebar-width: 18rem;
88
--theme-right-sidebar-width: 18rem;
99
/*
1010
Minimum visual horizontal spacing from the edges of the viewport,
@@ -15,13 +15,19 @@
1515
--doc-padding-block: 0.5rem;
1616
--max-width: 100%;
1717
--cur-viewport-height: 100vh;
18+
/* Font sizes */
19+
--theme-text-base: 1rem;
20+
--theme-text-sm: 0.9375rem;
21+
--theme-text-xs: 0.875rem;
1822
}
1923

2024
@media (min-width: 50em) {
2125
:root {
2226
--min-spacing-inline: 1.5rem;
2327
--doc-padding-block: 1rem;
2428
--max-width: 46em;
29+
--theme-text-sm: 0.875rem;
30+
--theme-text-xs: 0.8125rem;
2531
}
2632
}
2733

‎src/components/DeployGuidesNav.astro‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ const services: Service[] = [
8383
}
8484

8585
.filter-text {
86-
font-size: 0.875rem;
86+
font-size: var(--theme-text-sm);
8787
white-space: nowrap;
8888
}
8989

‎src/components/IslandsDiagram.astro‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,6 @@ function slotDefault (slotName: string) {
7878

7979
.credit {
8080
text-align: right;
81-
font-size: 0.8125em;
81+
font-size: var(--theme-text-xs);
8282
}
8383
</style>

‎src/components/LeftSidebar/LeftSidebar.astro‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,9 @@ for (const section of sidebarSections) {
4545
<ul class={`nav-groups`}>
4646
<SidebarContent type={'learn'} defaultActiveTab={activeTab} sidebarSections={learnSections} {currentPageMatch} />
4747
<SidebarContent type={'api'} defaultActiveTab={activeTab} sidebarSections={apiSections} {currentPageMatch} />
48-
<CommunityMenu hideOnLargerScreens={true} />
48+
<li>
49+
<CommunityMenu hideOnLargerScreens={true} />
50+
</li>
4951
<li style="text-align: center;">
5052
<ThemeToggleButton
5153
client:visible
@@ -69,9 +71,10 @@ for (const section of sidebarSections) {
6971
nav {
7072
width: 100%;
7173
height: 100%;
72-
padding-top: 0rem;
74+
font-size: var(--theme-text-sm);
7375
}
7476
.nav-groups {
77+
padding-top: 1rem;
7578
max-height: 100%;
7679
overflow-x: visible;
7780
overflow-y: auto;

0 commit comments

Comments
 (0)