Skip to content

Commit e0371de

Browse files
outofambitoutofambit
authored
Merge pull request #360 from processing/more-docs
More docs
2 parents fe82394 + 11099ce commit e0371de

4 files changed

Lines changed: 141 additions & 4 deletions

File tree

‎docs/content_overview.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Which content is where?
2+
3+
## Reference
4+
5+
- Stored in `/src/content/reference/`
6+
- English version is pulled in from p5.js repo via [scripts](./scripts.md)
7+
- Other translations are stored directly in this repo under the corresponding language folder in `/src/content/reference/`
8+
9+
## Examples
10+
11+
- Stored in `/src/content/examples/`
12+
- All translations are stored and edited directly in this repo under the corresponding language folder in `/src/content/examples/`
13+
14+
## Tutorials
15+
16+
- Stored in `/src/content/tutorials/`
17+
- All translations are stored and edited directly in this repo under the corresponding language folder in `/src/content/tutorials/`
18+
19+
## Contributor docs
20+
21+
- Stored in `/src/content/contributor-docs/`
22+
- All translations are pulled in from p5.js repo via [scripts](./scripts.md)
23+
24+
## Libraries
25+
26+
- Stored in `/src/content/libraries/en/`
27+
- There are no translations for these entries
28+
- See [Contributing Libraries](./contributing_libraries.md) for more info
29+
30+
## People
31+
32+
- Stored in `/src/content/people/en/`
33+
- There are no translations for these entries
34+
- New entries are pulled in from p5.js repo via [scripts](./scripts.md), existing ones are edited directly in this repository
35+
36+
## Events
37+
38+
- Stored in `/src/content/events/`
39+
- All translations are stored and edited directly in this repo under the corresponding language folder
40+
41+
## Homepage
42+
43+
- Stored in `/src/content/homepage/`
44+
- All translations are stored and edited in their respective language folder there
45+
46+
## About page
47+
48+
- All translations are stored in `/src/content/text-detail/[lang]/about.mdx` (where `[lang]` is the appropriate language code)
49+
50+
## Simple static pages (like Privacy Policy and Code of Conduct)
51+
52+
- Stored in `/src/content/text-detail/`
53+
- All translations are stored and edited in their respective language folder there
54+
- This includes simple general pages like Contact, Privacy Policy, Download, etc.
55+
56+
## Community Sketches
57+
58+
- Stored in a curation on [OpenProcessing](https://openprocessing.org)
59+
- This is only the gallery of community sketches. It doesn't include sketches that are embedded within tutorials, examples, or the reference.
60+
- See [Community Sketches](./community_sketches.md) for more info

‎docs/localization.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,74 @@ Both of these routes use the [TutorialsLayout](/src/layouts/TutorialsLayout.astr
3232
The main difference between these two routing files is how they retrieve the correct translation. The English version retreives the English version of the content. The other translations retrieve their version of the content and then fill in any gaps with English versions. See `getCollectionInLocaleWithFallbacks()` for how this works.
3333

3434
Because of this subtle duplication, we try to keep the files in `src/pages/` as short as possible and move rendering logic into the [layout files](/src/layouts/).
35+
36+
## Using translations
37+
38+
When you are editing an existing page or adding a new one, there are two ways to use individual translated strings from the ["ui" content collection](/src/content/ui/). It depends on what kind of file you are editing:
39+
40+
### Astro files (`.astro`)
41+
42+
In .astro files you can use `getCurrentLocale()` and `getUiTranslator()` like so:
43+
44+
```astro
45+
---
46+
import { getCurrentLocale, getUiTranslator } from "@i18n/utils";
47+
48+
const currentLocale = getCurrentLocale(Astro.url.pathname);
49+
const t = await getUiTranslator(currentLocale);
50+
51+
const introText = t("New intro paragraph");
52+
---
53+
54+
<p>{introText}</p>
55+
```
56+
57+
`getCurrentLocale()` extracts the current locale code from the page's URL. Passing this to `getUiTranslator()` tells it which language to return translations for. Whenever a translation is missing for the given language, it will return the string in English (the fallback language).
58+
59+
The returned translator function (`t`) accepts a key or list of keys to know which translation string to return. Check [the English translation file to see the most complete list of what's already available](/src/content/ui/en.yaml). The keys you pass to the translator function are used to lookup a string in that file (or the equivalent of it in the current language). If the `en.yaml` file has the following content:
60+
61+
```yaml
62+
Forum: Forum
63+
Sketches: Sketches
64+
Libraries: Libraries
65+
People: People
66+
New intro paragraph: Welcome to this new page we just added!
67+
sectionTitles:
68+
main: An intro to squares
69+
```
70+
71+
Then `t("New intro paragraph")` will return "Welcome to this new page we just added!" and `t("sectionTitles", main)` will return "An intro to squares".
72+
73+
### Preact files (`.jsx`, `.tsx`)
74+
75+
Preact files cannot access the current url directly with `Astro.url.pathname`, so we have to take a different approach: we pass in a translation object as a prop. Every Preact component in this project is rendered from an Astro layout or component file, so we can rely on it to get the correct current language.
76+
77+
In our astro file, we use our old friend `getCurrentLocale()` and then pass the result to `getUiTranslationWithFallback()` to get an object of translations. And pass it to the `HelloButton` component.
78+
79+
```astro
80+
---
81+
import { getCurrentLocale, getUiTranslationWithFallback } from "@i18n/utils";
82+
import { HelloButton } from "@components/HellowButton/index.jsx"
83+
84+
const currentLocale = getCurrentLocale(Astro.url.pathname);
85+
const uiTranslations = await getUiTranslationWithFallback(currentLocale);
86+
---
87+
88+
<HelloButton uiTranslations={uiTranslations} />
89+
90+
```
91+
92+
And then in the HelloButton Preact component, we acess the translations using object keys:
93+
94+
```jsx
95+
export const HelloButton = (props) => {
96+
const { uiTranslations } = props;
97+
return <button>{uiTranslations["hello"]}</button>;
98+
};
99+
```
100+
101+
Essentially, the arguments you would pass to `t` in the first example for astro files are the same you would pass as keys to the `uiTranslations` object. If its a nested key, that looks like:
102+
103+
```jsx
104+
uiTranslations["sectionTitles"]["main"];
105+
```

‎docs/scripts.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
1-
# Scripts
1+
# Content Scripts
22

33
This repo includes a few scripts to pull content from external sources, primarily the [p5.js repo](https://github.com/processing/p5.js).
44

55
They are all runnable via npm scripts.
66

7-
## Search Indices Build Script
7+
## After a p5.js release
88

9-
`npm run build:search` generates metadata about the content of the website so the search functionality can show relevant results.
9+
To update the content on the p5.js website following a new release of p5.js, you should run all of these commands to pull in the latest content. **Be sure to run the search indices script last as it depends on the results of the other scripts to be accurate.**
1010

1111
## Contributor Docs Build Script
1212

13-
`npm run build:contributor-docs` copies the contributor docs from the p5.js website repo and places them into the [contributor docs content collection](/src/content/contributor-docs).
13+
`npm run build:contributor-docs` copies the contributor docs from the p5.js repo and places them into the [contributor docs content collection](/src/content/contributor-docs).
1414

1515
## Reference Build Script
1616

@@ -19,3 +19,7 @@ They are all runnable via npm scripts.
1919
## Contributors List Build Script
2020

2121
`npm run build:contribtuors` parses the list of contributors from the all contributors [config file](https://github.com/processing/p5.js/blob/main/.all-contributorsrc) in the p5.js repo and adds entries in the [people collection](src/content/people/en) for anyone who is missing. These are used to render the list of contributors on the [People page](https://p5js.org/people/). This script will **not** remove or update existing entries, that must be done manually.
22+
23+
## Search Indices Build Script
24+
25+
`npm run build:search` generates metadata about the content of the website so the search functionality can show relevant results. This script should usually be run after any of the above scripts are run.

‎docs/technical_overview.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@ The website code is divided into a few main folders:
2828
- `src/components/` holds UI elements that are rendered on different pages of the website. Things like basic buttons, as well as more specialized things like the top navigation menus are here.
2929
- `src/layouts/` this contains the basic visual structure of each page. If you are looking to edit a specific page of the website, finding the layout for it in this folder is a great place to start.
3030
- `src/pages/` these files are primarily used to create the routes (the different URLs) for the pages of the website and pull content from `src/content/`. Note that every route basically exists twice: once in `src/pages/` and again in `src/[locale]/pages/` to support localized urls. Read more about this in [./localization-architecture.md]
31+
- `src/api/` holds the logic for fetching information from the OpenProcessing API, where all the gallery sketches for this website are stored
32+
- `src/i18n/` holds the utilities and configuration for working with translations
3133
- `src/scripts/` contains utility scripts that update the files in `src/content/` with changes in the p5.js repo
3234
- `styles/` contains globally applied css styles for the website
3335
- `test/` contains a set of unit tests that cover some important utility functions and key components

0 commit comments

Comments
 (0)