|
| 1 | +# Contributing to p5.js website internationalization (i18n) |
| 2 | + |
| 3 | +If you want to contribute with p5.js website translations you are in the right place. The translation of the p5.js website to languages other than English is part of its internationalization -abbreviated [*i18n*](https://en.wikipedia.org/wiki/Internationalization_and_localization)- process. You can improve content that has been already translated -at the reference, examples or other pages within the website- as well as start a new language translation. |
| 4 | + |
| 5 | +## Table of Contents |
| 6 | + |
| 7 | +* [How the website works](#how-the-website-works) |
| 8 | +* [Setting up before start your contribution](#setting-up-before-start-your-contribution) |
| 9 | +* [Before submitting a Pull Request](#before-submitting-a-pull-request) |
| 10 | +* [File Structure](#file-structure) |
| 11 | +* [Start a new translation](#start-a-new-translation) |
| 12 | +* [Working on existing translations](working-on-existing-translations) |
| 13 | + * [Translation of all pages except Reference and Examples](#translation-of-all-pages-except-reference-and-examples) |
| 14 | + * [Translation of Reference](#translation-of-reference) |
| 15 | + * [Translation of Examples](#translation-of-examples) |
| 16 | + |
| 17 | +## How the website works |
| 18 | +1. Due to internationalization (i18n) this website is built from templates that retrieve the text content from data files |
| 19 | +2. There are three kind of pages and each works differently: |
| 20 | + * [Reference](#translation-of-reference): Pages are built in English and swapped to other languages using JS on the front-end. Translation content is stored in a JSON object. |
| 21 | + * [Examples](#translation-of-examples): Examples pages are built from from templates handlebars with handlebars, while examples are stored in JS files. |
| 22 | + * [Other](#translation-of-all-pages-except-reference-and-examples): Pages are built from templates in which handlebars point to the content in the actual language when rendered. |
| 23 | +3. Every time a modification is submitted the website is rendered again. |
| 24 | +4. Built web is stored under `dist/` directory whilst data and templates are stored under `src/` directory. For further information check the [File Structure](#file-structure). |
| 25 | +5. When collaborating code editing have to be done in files under `src/`, but not under `dist/` as files in there are removed and recreated on build. |
| 26 | + |
| 27 | + |
| 28 | +## Setting up before start your contribution |
| 29 | +*Please do this only once before you start your contribution.* |
| 30 | +1. Install node.js by following the instructions [here](https://nodejs.org/en/download/). |
| 31 | +2. [Fork](https://help.github.com/articles/fork-a-repo/) the p5.js-website repository to your Github account. Click the *Fork* button on the upper-right side of the p5.js-website Github repo. This will automatically open your fork repo on Github. |
| 32 | + |
| 33 | +3. On your fork click the green *Clone or download* button. It will display a bar from where you can copy your `repo_URL`. |
| 34 | + |
| 35 | +4. Open your command-line interface (CLI) and [clone](https://help.github.com/articles/cloning-a-repository/) your fork of the p5.js-website repository to `your_directory` on your laptop by typing: |
| 36 | +```bash |
| 37 | +$ git clone repo_URL |
| 38 | +``` |
| 39 | +5. Go to the repository's directory `[your_directory]/p5.js-website/` and install all the packages and dependencies for the website by typing (if you work on Mac it should be like `Users/[your_user]/[your_directory]/p5.js-website/`): |
| 40 | +```bash |
| 41 | +$ npm install |
| 42 | +``` |
| 43 | +6. Check if the packages are correctly installed by typing: |
| 44 | +```bash |
| 45 | +$ npm run watch |
| 46 | +``` |
| 47 | +7. This should open a window in your browser with the site running at http://localhost:9000. |
| 48 | +8. Set `github.com/processing/p5.js-website` as the upstream of your local. Type the following to list the configured remote for your fork (or follow this [tutorial](https://help.github.com/articles/configuring-a-remote-for-a-fork/)): |
| 49 | +```bash |
| 50 | +$ git remote -v |
| 51 | +origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch) |
| 52 | +origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push) |
| 53 | +``` |
| 54 | +Then specify a new remote upstream for your fork (don't forget that by doing this you are setting the upstream for your local fork, but not for your fork on Github): |
| 55 | +```bash |
| 56 | +$ git remote add upstream github.com/processing/p5.js-website |
| 57 | +``` |
| 58 | +Finally verify if your remote upstream has been set (it should look like this): |
| 59 | +```bash |
| 60 | +$ git remote -v |
| 61 | +origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch) |
| 62 | +origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push) |
| 63 | +upstream https://github.com/processing/p5.js-website.git (fetch) |
| 64 | +upstream https://github.com/processing/p5.js-website.git (push) |
| 65 | +``` |
| 66 | + |
| 67 | +## Before submitting a Pull Request |
| 68 | +*Please do this every time you submit a PR.* |
| 69 | +1. Sync your fork to keep it up-to-date with the upstream repository following the next commands or this [tutorial](https://help.github.com/articles/syncing-a-fork/). First fetch the upstream repo and its commits -commits will be stored on your local fork- and then merge changes form upstream to your local: |
| 70 | +```bash |
| 71 | +$ git fetch upstream |
| 72 | +$ git merge upstream/master |
| 73 | +``` |
| 74 | +2. Make changes only at files under the `src/` directory. |
| 75 | +3. Check if your changes are correct and don't break the website render by typing `npm run watch`. |
| 76 | +4. Commit the files you have changed, type: |
| 77 | +```bash |
| 78 | +$ git add -A |
| 79 | +$ git commit -m "add a message to your commit" |
| 80 | +$ git push |
| 81 | +``` |
| 82 | +5. Commit to your repository at your github account and create a new [Pull Request](https://github.com/processing/p5.js-website/wiki/Pull-requests). Click the *Pull Reques* tab on your fork page and then click the green button *New Pull Request*. |
| 83 | + |
| 84 | + |
| 85 | +## File Structure |
| 86 | +Under this repo there are two directories in which we have to focus: |
| 87 | +``` |
| 88 | +p5.js-website/ |
| 89 | + src/ |
| 90 | + dist/ |
| 91 | +``` |
| 92 | +* `dist/`: the actual website is stored under this directory and its files **must never be modified by hand**, they are overwritten each time the web is built. |
| 93 | +* `src/`: contains the files from where the page is rendered, which means .hbs and .yml files for the website itself and .js and .json files for Reference and Examples. **All your changes must be done here**. |
| 94 | + * `assets/` – All static files (imgs, css, fonts, js, p5_featured homepage sketches) |
| 95 | + * Note: if you make edits here you must restart the server to see your changes. To see changes immediately, you can edit the assets files in the dist directory, but need to copy and paste your updated work here for it to be saved. |
| 96 | + * `data/` – contains translation files and assets for examples (audio files, fonts, videos). |
| 97 | + * `templates/` |
| 98 | + * `layouts/` – default.hbs is main page template. |
| 99 | + * `pages/` – Contains each of the pages of the p5 site, these get inserted in `{{> body }}` tag of default layout. |
| 100 | + * `partials/` – These are reusable pieces that can get added to any page or layout, they correspond to other `{{> filename }}` tags in the pages or default layout. |
| 101 | +* `Gruntfile.js` – This file contains all the tasks for using assemble and YAML to generate the final, static site. It uses the task runner [grunt](http://gruntjs.com/). |
| 102 | + |
| 103 | +## Start a new translation |
| 104 | +1. Define an abbreviation for your language following the [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) standard. It's expected that abbreviations are two-letter, but for macro languages can be added extra extensions depending on each case. |
| 105 | +2. Open a new issue and propose the addition of the new language. If the both the proposal and the abbreviation are approved proceed with the next step. |
| 106 | +3. Add an entry with the new language abbreviation at `package.json` to the `languages` category -located under the repository root directory. |
| 107 | +```JSON |
| 108 | +"languages": [ |
| 109 | + "en", |
| 110 | + "es", |
| 111 | + "zh-Hans", |
| 112 | + "new language here" |
| 113 | +], |
| 114 | +``` |
| 115 | +4. Duplicate `en.yml` -stored under `src/data/`- and name it `language_abbreviation.yml`. For example, when the Spanish version was created it was named `es.yml`. Check [How the website works](#how-the-website-works) and [File Structure](#file-structure) for further information. |
| 116 | +5. Duplicate `es.json` -stored under `src/data/reference/`- and name it `[language_abbreviation].json`. |
| 117 | + |
| 118 | +## Working on existing translations |
| 119 | + |
| 120 | +### Translation of all pages except Reference and Examples |
| 121 | +Each webpage is written in [.hbs](https://www.npmjs.com/package/hbs) format -files created with the library Handlebars and written using HTML rules- using handlers to access the i18n data of each language and render. Each handler binds an specific spot on the HTML script with an specific content stored in a database, and is replaced by it when the page is built. Hbs files are stored under `src/template/pages`. |
| 122 | + |
| 123 | +The i18n data is stored in [.yml](https://en.wikipedia.org/wiki/YAML) files in the `src/data` folder of this repo. For example, under the above mentioned path the .yml files for English, Spanish and Chinese can be found as follows: |
| 124 | + |
| 125 | +``` |
| 126 | +en.yml |
| 127 | +es.yml |
| 128 | +zh-Hans.yml |
| 129 | +``` |
| 130 | + |
| 131 | +Within the .hbs pages there are tags that replace the actual content and look like this: `{{#i18n "MyKeyword"}}{{/i18n}}`. For example the *Download* tag at the main bar looks like this: |
| 132 | + |
| 133 | +```html |
| 134 | +<li><a href="{{root}}/download/">{{#i18n "Download"}}{{/i18n}}</a></li> |
| 135 | +``` |
| 136 | + |
| 137 | +In this example "Download" corresponds to the key-value pair for the translation of that content to other languages. Each key-value can point to a word as well as a phrase. and there must be a key-value for each handler entry in every language, otherwise the website render process can be broken. |
| 138 | + |
| 139 | +Each page contains YAML "front matter" at the top which includes a title and (optional) slug field. The title corresponds to the section in which to place the i18n key-value pairs. (Note: each page has only one title, so for partials within the `partials` folder, place the i18n pairs at the top level). The slug corresponds to the folder in which the page will be placed. This should generally match the folder structure within the `pages` folder. |
| 140 | + |
| 141 | +For nested pages -for example `p5js.org/es/learn/color.html`- the slug of the .hbs document must match the upper folder, in this case `learn`. This is directly related with the way handlers are displayed in the .yml file. For example, all the handlers for the `learn` page are written under its slug with a tab as follows: |
| 142 | + |
| 143 | +```javascript |
| 144 | +learn: |
| 145 | + learn-title: "Aprender" |
| 146 | + learn1: "Estos tutoriales proveen una revisión en mayor profundidad o paso a paso sobre temas particulares. Revisa la " |
| 147 | +``` |
| 148 | + |
| 149 | +But for nested pages it's important not to create a new slug for each page, because it can make the .hbs files not to find the handlers when calling the i18n data. So, for the page color **it is not needed to create a new** `slug: color/` like: |
| 150 | + |
| 151 | +```javascript |
| 152 | +color: |
| 153 | + color-title: "Color" |
| 154 | +``` |
| 155 | + |
| 156 | +Instead of this, the color-related handler must be added to the `learn` list of handlers. For English version, the site will follow the same top-level hierarchy as the original site. When you switch to a different language, the permalink and file structure will include the language abbreviation immediately following the root url. (ex: `https://p5js.org/es/get-started/`) |
| 157 | + |
| 158 | +**Yml files can break the page compilation** process under syntax issues as double quotes within the text. Each YAML handler must be written as `color-rgb-title: "Color RGB"`, which means that the handler `color-rgb-title` has assigned the content `"Color RGB"` in the current language .yml file. |
| 159 | + |
| 160 | +In some cases, the text translated from the original .hbs file (written in HTML) included double quotes used for highlight some idea. In those cases remember to use the scape command `\` before the quotes, otherwise your compiler will interpret it as a syntax error due the handler finished more the one time. |
| 161 | + |
| 162 | +### Translation of Reference |
| 163 | +* The reference works a bit differently. The pages are built in English based on the inline documentation in the source code. They are then swapped out using JS on the front-end. |
| 164 | +* The top level keys in the JSON object correspond to the page headings, menu, footer, etc. You can see all the swaps in [this file](https://github.com/processing/p5.js-website/blob/master/dist/reference/index.html#L130). |
| 165 | +* The "p5" key in the JSON object contains individual keys for each reference entry, indexed by variable/function/object name. |
| 166 | +* Any entries in the JSON object which are not filled in will be left in English when the page is loaded. |
| 167 | +* This is a somewhat hacky solution and not ideal. However, it comes from balancing the desire to have documentation directly in the source code, with the unwieldiness of having multiple languages of documentation inline. It will be our working solution until a better one is found. |
| 168 | +* The source content for the reference is handled inline in the [p5.js source code](https://github.com/processing/p5.js). See [Inline documentation](https://github.com/processing/p5.js/blob/master/developer_docs/inline_documentation.md) in the p5.js repo for information on how to contribute. |
| 169 | + |
| 170 | +### Translation of Examples |
| 171 | +The examples are handled a bit differently from other pages. |
| 172 | +* All examples pages are built from `src/data/examples`. |
| 173 | +* Within the examples folder, there is a folder for each of the three languages we currently support: `en/`, `es/`, and `zh-Hans/`. When adding a new example, first add an English version of the file to the `en/` folder, then make sure it is duplicated in the same place in all other languages, then translate for whichever languages you can. If you have created a new folder, add entries to the YAML files with the foldername as the key. |
| 174 | +* The folder, file, and numbering structure should match exactly between the different languages. Do not change the filenames. The text for the example name, description, and source code are all in the .js files in the folders. |
| 175 | +* Assets for the examples are placed in `src/data/examples/assets`. |
| 176 | +* Translations for the topic headers on the example index page are done in the YAML files (`src/data/*.yml`). |
0 commit comments