resovling i18n issues

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: processing
+custom: https://processingfoundation.org/

.travis.yml

@@ -9,4 +9,4 @@ deploy:
   keep-history: true
   local-dir: dist/
   on:
-    branch: master
+    branch: main

Gruntfile.js

@@ -11,7 +11,6 @@ const fs = require('fs').promises;
 const pkg = require('./package.json');
 
 module.exports = function(grunt) {
-
   require('time-grunt')(grunt);
   require('load-grunt-tasks')(grunt);
 
@@ -83,8 +82,8 @@ module.exports = function(grunt) {
         options: {
           expand: true,
           flatten: true,
-          helpers: ['<%= config.src %>/assets/js/translation.js'],
           assets: '<%= config.dist %>/assets',
+          helpers: ['helpers/translation.js', 'helpers/cache-busting.js'],
           layout: '<%= config.src %>/templates/layouts/default.hbs',
           data: [
             '<%= config.src %>/data/**/*.{json,yml}',
@@ -98,24 +97,24 @@ module.exports = function(grunt) {
           i18n: {
             languages: pkg.languages,
             templates: [
-              "<%= config.src %>/templates/pages/**/*.hbs",
+              '<%= config.src %>/templates/pages/**/*.hbs',
             ]
           },
           permalinks: {
             structure: ':lang/:slug/:base:ext',
             patterns: [
               {
                 pattern: ':lang',
-                replacement: function () {
+                replacement: function() {
                   return this.language.toLowerCase() === 'en' ? '' : this.language;
                 }
               },
               {
                 pattern: ':base',
                 replacement: function () {
                   var check = this.basename.lastIndexOf(this.language.toLowerCase());
-                  if (check > -1){
-                    return this.basename.substring(0, check-1);
+                  if (check > -1) {
+                    return this.basename.substring(0, check - 1);
                   } else return this.basename;
                 }
               }
@@ -133,9 +132,9 @@ module.exports = function(grunt) {
           baseUrl: '<%= config.src %>/yuidoc-p5-theme-src/scripts/',
           mainConfigFile: '<%= config.src %>/yuidoc-p5-theme-src/scripts/config.js',
           name: 'main',
-          out: '<%= config.src %>/templates/pages/reference/assets/js/reference.js',
+          out: '<%= config.src %>/assets/js/reference.js',
           optimize: 'none',
-          generateSourceMaps: true,
+          generateSourceMaps: false,
           findNestedDependencies: true,
           wrap: true,
           paths: {
@@ -283,8 +282,8 @@ module.exports = function(grunt) {
           },
           {
             expand: true,
-            cwd: '<%= config.src %>/assets',
-            src: 'css/**/*',
+            cwd: '<%= config.dist %>/assets',
+            src: 'css/all.css',
             dest: '<%= config.src %>/offline-reference/'
           },
           {
@@ -411,8 +410,8 @@ module.exports = function(grunt) {
     'requirejs:yuidoc_theme',
     'requirejs',
     'copy',
-    'assemble',
     'optimize',
+    'assemble',
     'file_append',
     'compress',
     'i18n',

README.md

@@ -4,11 +4,11 @@
 
 ## How To Contribute
 
-Known bugs and intended new features are tracked using [GitHub issues](https://github.com/processing/p5.js-website/issues). If you'd like to start working on an existing issue, comment on the issue that you plan to work on it so other contributors know it's being handled and can offer help. Once you have completed your work on this issue, [submit a pull request (PR)](https://github.com/processing/p5.js/blob/master/contributor_docs/preparing_a_pull_request.md) against the p5.js master branch. In the description field of the PR, include "resolves #XXXX" tagging the issue you are fixing. If the PR addresses the issue but doesn't completely resolve it (ie the issue should remain open after your PR is merged), write "addresses #XXXX".
+Known bugs and intended new features are tracked using [GitHub issues](https://github.com/processing/p5.js-website/issues). If you'd like to start working on an existing issue, comment on the issue that you plan to work on it so other contributors know it's being handled and can offer help. Once you have completed your work on this issue, [submit a pull request (PR)](https://github.com/processing/p5.js/blob/main/contributor_docs/preparing_a_pull_request.md) against the p5.js master branch. In the description field of the PR, include "resolves #XXXX" tagging the issue you are fixing. If the PR addresses the issue but doesn't completely resolve it (ie the issue should remain open after your PR is merged), write "addresses #XXXX".
 
 If you discover a bug or have an idea for a new feature you'd like to add, begin by submitting an issue. Please do not simply submit a pull request containing the fix or new feature without making an issue first, we will probably not be able to accept it. Once you have gotten some feedback on the issue and a go ahead to address it, you can follow the process above to add the fix or feature.
 
-We recognize all types of contributions. This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Add yourself to the [p5.js repository readme](https://github.com/processing/p5.js/blob/master/README.md#contributors) by following the [instructions here](https://github.com/processing/p5.js/issues/2309)!
+We recognize all types of contributions. This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Add yourself to the [p5.js repository readme](https://github.com/processing/p5.js/blob/main/README.md#contributors) by following the [instructions here](https://github.com/processing/p5.js/issues/2309)!
 
 
 ## Setup
@@ -47,7 +47,7 @@ Once you've setup the site, type `npm run watch` to run the website. This should
 If you've contributed to this website (or any other part of the p5.js project), add yourself [here](https://github.com/processing/p5.js#contributors). Instructions to do this can be found at the bottom of the section.
 
 ## Etc
-* [Instructions for contributing to website translation/internationalization](https://github.com/processing/p5.js-website/blob/master/contributor_docs/i18n_contribution.md)
+* [Instructions for contributing to website translation/internationalization](https://github.com/processing/p5.js-website/blob/main/contributor_docs/i18n_contribution.md)
 * [Introducción a p5.js](https://github.com/processing/p5.js-getting-started-es) - The repository for the book and PDF production of [Introducción a p5.js](http://p5js.org/books/).
 
 ## Externally hosted language versions

contributor_docs/Adding_examples.md

@@ -10,25 +10,26 @@ Examples help demonstrate different programming concepts and functionality of th
 3. [Clone](https://help.github.com/articles/cloning-a-repository/) your new fork of the repository from GitHub onto your local computer.
 4. Using the command line, navigate to the `src/data/examples/build_examples` folder, and install all its necessary dependencies with npm.
 
-    ```bash
-    cd src/data/examples/build_examples
-    npm install
-    ```
+   ```bash
+   cd src/data/examples/build_examples
+   npm install
+   ```
 
 ## Make an issue
 
 1. Open a new issue on the [p5.js-website repository](https://github.com/processing/p5.js-website/issues) listing the examples you are creating with your name, so efforts aren't duplicated.
 
-
 ## Create your example
 
-1. First, build and test the example code using your own HTML file, linking to the most recent version of p5.js. You can find examples to port here.
-    * Please use two spaces tabs and see this code style guide.
-    * Examples should typically be 710px wide, and a recommended height is 400px. You can modify these dimensions (especially the height) as appropriate.
+1. First, build and test the example code using your HTML file, linking to the most recent version of p5.js. You can find examples to port here.
+
+   - Please use two spaces tabs and see this code style guide.
+   - Examples should typically be 710px wide, and a recommended height is 400px. You can modify these dimensions (especially the height) as appropriate.
 
 2. At the top of the JS file you create, add a heading using the template below.
-    * The @name field determines the title of the example and the text of it's corresponding link on the examples page.
-    * The @frame field determines the dimensions of the example frame on the page. If you leave this field out, your running example will default to the size you set with createCanvas(). If you'd like to specify an alternate size (maybe because you have elements outside the canvas, for example), include the @frame line with dimensions separated by comma.
+
+   - The @name field determines the title of the example and the text of its corresponding link on the examples page.
+   - The @frame field determines the dimensions of the example frame on the page. If you leave this field out, your running example will default to the size you set with createCanvas(). If you'd like to specify an alternate size (maybe because you have elements outside the canvas, for example), include the @frame line with dimensions separated by a comma.
 
    ```jsdoc
    /*
@@ -43,29 +44,30 @@ Examples help demonstrate different programming concepts and functionality of th
 ## Add your example to p5js.org
 
 1. Place the JS file with your code and heading (do not include the HTML or p5.js files) in `src/data/examples/en/` of your local repository.
-    * The subfolder the file is placed in determines the topic heading the examples displays under on [p5js.org/examples](https://p5js.org/examples/). Add your file into the appropriate folder, or create a new one if necessary.
-    * If you create a new folder, you will also need to add the folder name to the `examples` section in the `src/data/en.yml`, `src/data/es.yml`, and `src/data/zh-Hans.yml` files in order for the headings to show up properly.
-    * The filename should follow the format: `XX_name_of_your_example.js`. The XX_ prefix (starting with 00) indicates the order that the files will show up on the page.
+
+   - The subfolder the file is placed in determines the topic heading the examples displays under on [p5js.org/examples](https://p5js.org/examples/). Add your file into the appropriate folder, or create a new one if necessary.
+   - If you create a new folder, you will also need to add the folder name to the `examples` section in the `src/data/en.yml`, `src/data/es.yml`, and `src/data/zh-Hans.yml` files for the headings to show up properly.
+   - The filename should follow the format: `XX_name_of_your_example.js`. The XX\_ prefix (starting with 00) indicates the order that the files will show up on the page.
 
 2. Place duplicate copies of the file in the corresponding folders in `src/data/examples/es/`, and `src/data/examples/zh-Hans/`. This allows us to build the Spanish and Chinese versions of the example. If you know either of these languages, feel free to translate the heading text and comments.
 
 3. If you have any extra files that need to be included (images, JSON, etc), place them in the `src/data/examples/assets` folder. Try to keep these files small.
 
-4. [Grunt](https://gruntjs.com/) should now be installed, and you can use it to build the website by navigating to the top level directory and typing:
+4. [Grunt](https://gruntjs.com/) should now be installed, and you can use it to build the website by navigating to the top-level directory and typing:
 
-    ```bash
-    npm run watch
-    ```
+   ```bash
+   npm run watch
+   ```
 
 5. A local build of the p5js.org site should open in your web browser and you can navigate to the examples page to see your changes.
 
 6. Once everything is ready, submit your changes as a [pull request](https://help.github.com/articles/creating-a-pull-request/).
 
 ## Notes about translating examples
 
-* The [p5js.org/examples](https://p5js.org/examples/) page is built from the data in [src/data/](https://github.com/processing/p5.js-website/tree/master/src/data).
-* Within the examples folder, there is a folder for each of the three languages we currently support: `en/`, `es/`, and `zh-Hans/`.
-* Translations for the topic headers on the example index page are done in the YML files `src/data/*.yml`.
+- The [p5js.org/examples](https://p5js.org/examples/) page is built from the data in [src/data/](https://github.com/processing/p5.js-website/tree/master/src/data).
+- Within the examples folder, there is a folder for each of the three languages we currently support: `en/`, `es/`, and `zh-Hans/`.
+- Translations for the topic headers on the example index page are done in the YML files `src/data/*.yml`.
 
 ## To add examples
 
@@ -75,7 +77,6 @@ Examples help demonstrate different programming concepts and functionality of th
 
 ## When adding a new example
 
-1. 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.
+1. 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.
 2. 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.
-3. If you have created a new folder, add entries to the "Examples" section of each of the YML files `src/data/*.yml` with the foldername as the key.
-
+3. If you have created a new folder, add entries to the "Examples" section of each of the YML files `src/data/*.yml` with the folder name as the key.

contributor_docs/i18n_contribution.md

@@ -85,7 +85,7 @@ If you want to contribute with p5.js website translations, you are in the right
 
     ```
     $ git fetch upstream
-    $ git merge upstream/master
+    $ git merge upstream/main
     ```
 
 2. Make changes only at files under the `src/` directory.
@@ -137,7 +137,7 @@ p5.js-website/
 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.
 5. Duplicate `es.json` - stored under `src/data/reference/` - and name it `[language_abbreviation].json`.
 6. Duplicate `en` folder - stored under `src/data/examples` - and name it `language_abbreviation`.
-7. Add a new menu entry in [`src/templates/partials/i18n.hbs`](https://github.com/processing/p5.js-website/blob/master/src/templates/partials/i18n.hbs#L8) like so `<li><a href='#' lang='[language_abbreviation]' data-lang='[language_abbreviation]'>[language_name]</a></li>`.
+7. Add a new menu entry in [`src/templates/partials/i18n.hbs`](https://github.com/processing/p5.js-website/blob/main/src/templates/partials/i18n.hbs#L8) like so `<li><a href='#' lang='[language_abbreviation]' data-lang='[language_abbreviation]'>[language_name]</a></li>`.
 
 ## Working on existing translations
 
@@ -198,12 +198,15 @@ In some cases, the text translated from the original .hbs file (written in HTML)
 
 ### Translation of Reference
 
-* 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.
-* 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/src/templates/pages/reference/index.hbs#L60).
+* The reference works a bit differently. The pages are built in English based on the inline documentation in the p5.js source code. The English text is then swapped out with the appropriate translation using JS on the front-end.
+* The inline API documentation is automatically extracted from the p5.js repository using [YUIdoc](https://yui.github.io/yuidoc/) and saved in a [JSON file](https://github.com/processing/p5.js-website/blob/main/src/templates/pages/reference/data.json). 
+* The translation files are created from the data.json file, but have a different structure (i.e. [es.json](https://github.com/processing/p5.js-website/blob/main/src/data/reference/es.json)).
+* 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/main/src/templates/pages/reference/index.hbs#L60).
 * The "p5" key in the JSON object contains individual keys for each reference entry, indexed by variable/function/object name.
 * Any entries in the JSON object which are not filled in will be left in English when the page is loaded.
+* The translated versions of the JSON file need to be manually created and updated.
 * 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.
-* 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/contributor_docs/inline_documentation.md) in the p5.js repo for information on how to contribute.
+* 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/main/contributor_docs/inline_documentation.md) in the p5.js repo for information on how to contribute.
 
 ### Translation of Examples
 

helpers/cache-busting.js

@@ -0,0 +1,24 @@
+module.exports.register = function(Handlebars, options) {
+  Handlebars.registerHelper('versionedAsset', function(options) {
+    // node libraries
+    const crypto = require('crypto');
+    const path = require('path');
+    const fs = require('fs');
+    const filePath = options.fn(this);
+    const hash = crypto.createHash('sha256');
+    // creating full path from the root dir to the file
+    const fullPath = path.join(__dirname, '..', 'dist', filePath);
+    let hashCode = '';
+    hash.on('readable', () => {
+      const data = hash.read();
+      if (data) hashCode = data.toString('hex');
+    });
+    hash.write(fs.readFileSync(fullPath, {
+        encoding: 'utf8'
+    }));
+    hash.end();
+    // creating a version string from first 6 hash characters
+    hashCode = '/' + filePath + '?v=' + hashCode.substr(0, 6);
+    return hashCode;
+  });
+};