Add basic "multilingual support" section

client/src/tokens/typography.stories.tsx

@@ -2,7 +2,7 @@ import React from 'react';
 import { fontFamily, typeScale } from './typography';
 
 const description = `
-Wagtail’s color palette is structured as design tokens, available as CSS classes.
+Wagtail’s type styles are structured as design tokens, available as CSS classes.
 `;
 
 export default {
@@ -16,7 +16,7 @@ export default {
 
 export const FontFamilies = () => (
   <div>
-    <p>Wagtail’s brand font is a system font stack:</p>
+    <p>Wagtail’s UI font is a system font stack:</p>
     <pre>{fontFamily.sans.join(', ')}</pre>
   </div>
 );

client/tailwind.config.js

@@ -93,8 +93,8 @@ module.exports = {
     }),
     /**
      * TypeScale plugin.
-     * This plugin generates component classes using tailwind's configuration for each object inside of the typeScale const.
-     * If the tailwind config is using a prefix such as 'w-' this will be included in the compiled css class eg. .w-h1
+     * This plugin generates component classes using tailwind's theme values for each object inside of the typeScale configuration.
+     * We have the `w-` prefix added in the configuration for documentation purposes, it needs to be removed here before Tailwind adds it back.
      */
     plugin(({ addComponents, theme }) => {
       const scale = {};

docs/contributing/developing.md

@@ -4,7 +4,9 @@
 
 Setting up a local copy of [the Wagtail git repository](https://github.com/wagtail/wagtail) is slightly more involved than running a release package of Wagtail, as it requires [Node.js](https://nodejs.org/) and npm for building JavaScript and CSS assets. (This is not required when running a release version, as the compiled assets are included in the release package.)
 
-If you're happy to develop on a virtual machine, the [vagrant-wagtail-develop](https://github.com/wagtail/vagrant-wagtail-develop) and [docker-wagtail-develop](https://github.com/wagtail/docker-wagtail-develop) setup scripts are the fastest way to get up and running. They will provide you with a running instance of the [Wagtail Bakery demo site](https://github.com/wagtail/bakerydemo/), with the Wagtail and bakerydemo codebases available as shared folders for editing on your host machine.
+If you're happy to develop on a local virtual machine, the [docker-wagtail-develop](https://github.com/wagtail/docker-wagtail-develop) and [vagrant-wagtail-develop](https://github.com/wagtail/vagrant-wagtail-develop) setup scripts are the fastest way to get up and running. They will provide you with a running instance of the [Wagtail Bakery demo site](https://github.com/wagtail/bakerydemo/), with the Wagtail and bakerydemo codebases available as shared folders for editing on your host machine.
+
+You can also set up a cloud development environment that you can work with in a browser-based IDE using the [gitpod-wagtail-develop](https://github.com/wagtail/gitpod-wagtail-develop) project.
 
 (Build scripts for other platforms would be very much welcomed - if you create one, please let us know via the [Slack workspace](https://github.com/wagtail/wagtail/wiki/Slack)!)
 
@@ -12,7 +14,7 @@ If you'd prefer to set up all the components manually, read on. These instructio
 
 ## Setting up the Wagtail codebase
 
-The preferred option is to install the correct version of Node using [Node Version Manager (nvm)](https://github.com/creationix/nvm) or [fnm](https://github.com/Schniz/fnm), which will always align the version with the supplied  `.nvmrc` file in the root of the project.
+The preferred way to install the correct version of Node is to use [Node Version Manager (nvm)](https://github.com/nvm-sh/nvm) or [Fast Node Manager (fnm)](https://github.com/Schniz/fnm), which will always align the version with the supplied  `.nvmrc` file in the root of the project. To ensure you are running the correct version of Node, run `nvm install` or `fnm install` from the project root.
 Alternatively, you can install [Node.js](https://nodejs.org/) directly, ensure you install the version as declared in the project's root `.nvmrc` file.
 
 You will also need to install the **libjpeg** and **zlib** libraries, if you haven't done so already - see Pillow's [platform-specific installation instructions](https://pillow.readthedocs.org/en/latest/installation.html#external-libraries).
@@ -24,18 +26,12 @@ $ git clone https://github.com/wagtail/wagtail.git
 $ cd wagtail
 ```
 
-With your preferred virtualenv activated, install the Wagtail package in development mode with the included testing and documentation dependencies:
+**With your preferred virtualenv activated,** install the Wagtail package in development mode with the included testing and documentation dependencies:
 
 ```console
 $ pip install -e '.[testing,docs]' -U
 ```
 
-Install Node through nvm (optional):
-
-```console
-$ nvm install
-```
-
 Install the tool chain for building static assets:
 
 ```console
@@ -67,13 +63,13 @@ run. You can run tests for only one part of Wagtail by passing in the path as
 an argument to `runtests.py` or `tox`:
 
 ```console
-$ # Running in the current environment
+# Running in the current environment
 $ python runtests.py wagtail
 
-$ # Running in a specified Tox environment
+# Running in a specified Tox environment
 $ tox -e py39-dj32-sqlite-noelasticsearch wagtail
 
-$ # See a list of available Tox environments
+# See a list of available Tox environments
 $ tox -l
 ```
 
@@ -81,10 +77,10 @@ You can also run tests for individual TestCases by passing in the path as
 an argument to `runtests.py`
 
 ```console
-$ # Running in the current environment
+# Running in the current environment
 $ python runtests.py wagtail.tests.test_blocks.TestIntegerBlock
 
-$ # Running in a specified Tox environment
+# Running in a specified Tox environment
 $ tox -e py39-dj32-sqlite-noelasticsearch wagtail.tests.test_blocks.TestIntegerBlock
 ```
 
@@ -98,9 +94,9 @@ $ django-admin makemigrations --settings=wagtail.test.settings
 
 ### Testing against PostgreSQL
 
-:::{note}
+```{note}
 In order to run these tests, you must install the required modules for PostgreSQL as described in Django's [Databases documentation](https://docs.djangoproject.com/en/stable/ref/databases/).
-:::
+```
 
 By default, Wagtail tests against SQLite. You can switch to using PostgreSQL by
 using the `--postgres` argument:
@@ -171,7 +167,7 @@ Our end-to-end browser testing suite also uses [Jest](https://jestjs.io/), combi
 
 ```console
 $ export DJANGO_SETTINGS_MODULE=wagtail.test.settings_ui
-$ # Assumes the current environment contains a valid installation of Wagtail for local development.
+# Assumes the current environment contains a valid installation of Wagtail for local development.
 $ ./wagtail/test/manage.py migrate
 $ ./wagtail/test/manage.py createcachetable
 $ DJANGO_SUPERUSER_EMAIL=admin@example.com DJANGO_SUPERUSER_USERNAME=admin DJANGO_SUPERUSER_PASSWORD=changeme ./wagtail/test/manage.py createsuperuser --noinput
@@ -243,7 +239,7 @@ The audit also states which parts of Wagtail have and haven’t been tested, how
 
 ## Compiling static assets
 
-All static assets such as JavaScript, CSS, images, and fonts for the Wagtail admin are compiled from their respective sources by `webpack`. The compiled assets are not committed to the repository, and are compiled before packaging each new release. Compiled assets should not be submitted as part of a pull request.
+All static assets such as JavaScript, CSS, images, and fonts for the Wagtail admin are compiled from their respective sources by Webpack. The compiled assets are not committed to the repository, and are compiled before packaging each new release. Compiled assets should not be submitted as part of a pull request.
 
 To compile the assets, run:
 
@@ -263,11 +259,11 @@ Wagtail’s UI component library is built with [Storybook](https://storybook.js.
 
 ```console
 $ export DJANGO_SETTINGS_MODULE=wagtail.test.settings_ui
-$ # Assumes the current environment contains a valid installation of Wagtail for local development.
+# Assumes the current environment contains a valid installation of Wagtail for local development.
 $ ./wagtail/test/manage.py migrate
 $ ./wagtail/test/manage.py createcachetable
 $ ./wagtail/test/manage.py runserver 0:8000
-$ # In a separate terminal:
+# In a separate terminal:
 $ npm run storybook
 ```
 
@@ -279,11 +275,11 @@ The Wagtail documentation is built by Sphinx. To install Sphinx and compile the
 
 ```console
 $ cd /path/to/wagtail
-$ # Install the documentation dependencies
+# Install the documentation dependencies
 $ pip install -e .[docs]
-$ # or if using zsh as your shell:
-$ #    pip install -e '.[docs]' -U
-$ # Compile the docs
+# or if using zsh as your shell:
+#    pip install -e '.[docs]' -U
+# Compile the docs
 $ cd docs/
 $ make html
 ```

docs/contributing/ui_guidelines.md

@@ -2,19 +2,19 @@
 
 Wagtail’s user interface is built with:
 
-- **HTML** using [Django templates](https://docs.djangoproject.com/en/stable/ref/templates/language/).
-- **CSS** using [Sass](https://sass-lang.com/) and [Tailwind](https://tailwindcss.com/).
-- **SVG** for our icons, minified with [SVGO](https://jakearchibald.github.io/svgomg/).
-- **JavaScript** with [TypeScript](https://www.typescriptlang.org/).
+- **HTML** using [Django templates](https://docs.djangoproject.com/en/stable/ref/templates/language/)
+- **CSS** using [Sass](https://sass-lang.com/) and [Tailwind](https://tailwindcss.com/)
+- **JavaScript** with [TypeScript](https://www.typescriptlang.org/)
+- **SVG** for our icons, minified with [SVGO](https://jakearchibald.github.io/svgomg/)
 
 ## Linting and formatting
 
 Here are the available commands:
 
-- `make lint` will run all linting, `make lint-server` lints templates, `make lint-client` lints JS/CSS
-- `make format` will run all formatting and fixing of linting issues. There is also `make format-server` and `make format-client`
+- `make lint` will run all linting, `make lint-server` lints templates, `make lint-client` lints JS/CSS.
+- `make format` will run all formatting and fixing of linting issues. There is also `make format-server` and `make format-client`.
 
-Have a look at our Makefile tasks and package.json scripts if you prefer more granular options.
+Have a look at our `Makefile` tasks and `package.json` scripts if you prefer more granular options.
 
 ## HTML guidelines
 
@@ -23,7 +23,7 @@ We use [djhtml](https://github.com/rtts/djhtml) for formatting and [Curlylint](h
 - Write [valid](https://validator.w3.org/nu/), [semantic](https://html5doctor.com/element-index/) HTML.
 - Follow [ARIA authoring practices](https://w3c.github.io/aria-practices/), in particular [No ARIA is better than Bad ARIA](https://w3c.github.io/aria-practices/#no_aria_better_bad_aria).
 - Use classes for styling, `data-` attributes for JavaScript behavior, IDs for semantics only.
-- For comments, use Django templates syntax instead of HTML.
+- For comments, use [Django template syntax](https://docs.djangoproject.com/en/stable/ref/templates/language/#comments) instead of HTML.
 
 ## CSS guidelines
 
@@ -39,5 +39,11 @@ We use [Prettier](https://prettier.io/) for formatting and [Stylelint](https://s
 
 We use [Prettier](https://prettier.io/) for formatting and [ESLint](https://eslint.org/) for linting.
 
-- We follow a laxer version of the [Airbnb styleguide](https://github.com/airbnb/javascript).
-- Familiarise yourself wit our [eslint-config-wagtail](https://github.com/wagtail/eslint-config-wagtail) configuration, which details our preferred code style.
+- We follow a somewhat relaxed version of the [Airbnb styleguide](https://github.com/airbnb/javascript).
+- Familiarise yourself with our [eslint-config-wagtail](https://github.com/wagtail/eslint-config-wagtail) configuration, which details our preferred code style.
+
+## Multilingual support
+
+This is an area of active improvement for Wagtail, with [ongoing discussions](https://github.com/wagtail/wagtail/discussions/8017).
+
+- Always use the `trimmed` attribute on `blocktrans` tags to prevent unnecessary whitespace from being added to the translation strings.