diff --git a/.github/workflows/backend.yml b/.github/workflows/backend.yml
index 36271ad82a..9901af95b9 100644
--- a/.github/workflows/backend.yml
+++ b/.github/workflows/backend.yml
@@ -79,6 +79,7 @@ jobs:
- run: npm install
working-directory: pontoon
- run: mkdir -p translate/dist translate/public
+ - run: zensical build -f documentation/zensical.toml
- run: python manage.py collectstatic
# Check if there are missing migrations
diff --git a/.gitignore b/.gitignore
index 78f625ecde..4115b4db97 100644
--- a/.gitignore
+++ b/.gitignore
@@ -21,6 +21,7 @@ venv/
/docker/config/server.env
/docs/_build
/docs/_gh-pages
+/documentation/site/
/env/
/media/
/pontoon/coverage.xml
diff --git a/.prettierignore b/.prettierignore
index 8fa9a198b7..80ffe30eed 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -2,6 +2,7 @@
translate/dist/
coverage/
docs/_build/
+documentation/
package-lock.json
specs/
.venv/
diff --git a/Makefile b/Makefile
index c1d0e0686c..3cad0c6868 100644
--- a/Makefile
+++ b/Makefile
@@ -9,7 +9,7 @@ SITE_URL ?= http://localhost:8000
USER_ID?=1000
GROUP_ID?=1000
-.PHONY: build build-translate build-server server-env setup run clean shell ci test test-translate test-server vitest pytest format lint types eslint prettier check-prettier ruff check-ruff dropdb dumpdb loaddb sync-projects requirements
+.PHONY: build build-translate build-server server-env setup run clean shell ci test test-translate test-server vitest pytest format lint types eslint prettier check-prettier ruff check-ruff dropdb dumpdb loaddb sync-projects requirements docs
help:
@echo "Welcome to Pontoon!\n"
@@ -39,7 +39,8 @@ help:
@echo " dumpdb Create a postgres database dump with timestamp used as file name"
@echo " loaddb Load a database dump into postgres, file name in DB_DUMP_FILE"
@echo " sync-projects Runs the synchronization task on all projects"
- @echo " requirements Compiles all requirements files with uv pip compile\n"
+ @echo " requirements Compiles all requirements files with uv pip compile"
+ @echo " docs Builds the documentation site\n"
translate/dist:
make build-translate
@@ -159,3 +160,7 @@ requirements:
# Pass --upgrade to upgrade all dependencies
# The arguments are passed through to `uv pip compile`
"${DC}" run --rm server //app/docker/compile_requirements.sh ${opts}
+
+docs:
+ "${DC}" run --rm server zensical build -f //app/documentation/zensical.toml
+ "${DC}" run --rm server .//manage.py collectstatic --noinput
diff --git a/bin/post_compile b/bin/post_compile
index 39928e070d..b17ad8a9b5 100644
--- a/bin/post_compile
+++ b/bin/post_compile
@@ -22,6 +22,9 @@ else
python manage.py migrate --noinput
fi
+echo "Building documentation..."
+zensical build -f documentation/zensical.toml
+
echo "Collecting static files..."
./manage.py collectstatic --noinput
diff --git a/docker-compose.yml b/docker-compose.yml
index f0731a4bb6..960894ec1f 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -15,6 +15,7 @@ services:
ports:
- '8000:8000'
volumes:
+ - ./documentation:/app/documentation
- ./pontoon:/app/pontoon
- ./requirements:/app/requirements
- ./translate:/app/translate
diff --git a/docker/Dockerfile b/docker/Dockerfile
index 9e5fcc509c..1c4511a13a 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -51,6 +51,9 @@ RUN npm install
COPY --chown=pontoon:pontoon ./docker/config/server.env .env
COPY --chown=pontoon:pontoon . /app/
+# Build documentation (generates static files)
+RUN zensical build -f documentation/zensical.toml
+
RUN python manage.py collectstatic
STOPSIGNAL SIGINT
diff --git a/docker/Dockerfile-mozcloud b/docker/Dockerfile-mozcloud
index 747440c18e..e1bea72f9f 100644
--- a/docker/Dockerfile-mozcloud
+++ b/docker/Dockerfile-mozcloud
@@ -92,6 +92,9 @@ COPY --from=node-builder /app/translate/public /app/translate/public
# Copy application code
COPY . /app/
+# Build documentation (generates static files)
+RUN zensical build -f documentation/zensical.toml
+
# Set up environment variables for collectstatic
ENV YUGLIFY_BINARY=/app/node_modules/.bin/yuglify
ENV TERSER_BINARY=/app/node_modules/.bin/terser
diff --git a/documentation/README.md b/documentation/README.md
new file mode 100644
index 0000000000..2faa032f4d
--- /dev/null
+++ b/documentation/README.md
@@ -0,0 +1,11 @@
+# Pontoon Documentation
+
+This folder contains the unified Pontoon documentation site, built with [Zensical](https://zensical.org/).
+
+It consolidates Pontoon documentation from three previously separate sites:
+
+| Audience | Previous location |
+|---|---|
+| Developers | [docs/](https://mozilla-pontoon.readthedocs.io/en/latest/) |
+| Localizers | [mozilla-l10n/localizer-documentation](https://mozilla-l10n.github.io/localizer-documentation/) |
+| Admins | [mozilla-l10n/documentation](https://mozilla-l10n.github.io/documentation/) |
diff --git a/documentation/docs/admin/adding-new-db-project.md b/documentation/docs/admin/adding-new-db-project.md
new file mode 100644
index 0000000000..5ea6627ed5
--- /dev/null
+++ b/documentation/docs/admin/adding-new-db-project.md
@@ -0,0 +1,46 @@
+# Adding a New DB Project
+
+DB projects are things like newsletters, marketing campaigns, surveys… They do not have a repository, and data is instead stored only in Pontoon’s database.
+
+The process to create a DB project is very similar to that of a regular one.
+
+## Create the project in Pontoon STAGE instance
+
+First you want to test that everything works using Pontoon staging server.
+
+Access Pontoon’s [admin console](https://pontoon.allizom.org/admin/) on the **stage server** and click **ADD NEW PROJECT**.
+
+* Name: name of the project (it will be displayed in Pontoon’s project selector).
+* Slug: used in URLs, will be generated automatically based on the repository’s name.
+* Locales:
+
+ * Select at least one locale. To make things faster it’s possible to copy supported locales from an existing project.
+ * You can uncheck the `Locales can opt-in` checkbox to prevent localizers from requesting this specific project.
+
+* Data Source: select `Database` in the list of options. This will hide the *Repositories* section and show a *Strings* section instead.
+* Strings: you can enter the initial set of strings here. Strings must be separated by new lines. If you leave this empty, you’ll be able to enter strings as a batch again after creating the project. Strings must be in `en-US`, and they will become the entities on that project. A resource named `database` will automatically be created.
+* For every other option, please refer to the [new project documentation](adding-new-project.md).
+
+Click **SAVE PROJECT** at the bottom of the page, and you’re done!
+
+## Create the project in Pontoon PROD instance
+
+At this point you need to repeat the same steps on the **production server**.
+
+Access Pontoon’s [admin console](https://pontoon.mozilla.org/admin/), add the same information you used on the staging server and make sure to select all supported locales for this project.
+
+The new project will immediately appear in the [public list of Projects](https://pontoon.mozilla.org/projects/).
+
+## Managing strings
+
+After you have created your project, you will be able to manage its source strings. On the admin project page (that you can find from the [admin console](https://pontoon.mozilla.org/admin/)), under the *Strings* section, you will find two links. The one called **MANAGE STRINGS** will lead you to a page where all strings are listed. There you can edit the string content, edit the string comment, add new strings (use the **NEW STRING** button) or remove existing strings (use the trashbin icon under the comment input). Once you’re done editing, click the **SAVE STRINGS** button to save your changes.
+
+## Downloading translations
+
+On the project’s admin page and on the Manage Strings page, you’ll find a **DOWNLOAD STRINGS** link. Clicking it will download a CSV file that contains all the translations in all enabled locales. The file format looks as follow:
+
+```CSV
+Source, fr, de
+Hello, Salut, Hallo
+World, Monde, Welt
+```
diff --git a/documentation/docs/admin/adding-new-locale.md b/documentation/docs/admin/adding-new-locale.md
new file mode 100644
index 0000000000..fec85d3e08
--- /dev/null
+++ b/documentation/docs/admin/adding-new-locale.md
@@ -0,0 +1,115 @@
+# Adding a New Locale
+
+## Verify if the locale is already available
+
+Access Django’s admin interface at `https://pontoon.mozilla.org/a/` (note that this is not the usual admin interface), then click `Locales`. In the next page search for the locale you want to add (safer to search for the locale code).
+
+## Add the new locale
+
+If the locale you need is not available, click the **ADD LOCALE+** button in the top right corner. For this example, let’s consider that the task is to add Amharic (am).
+
+You will need to complete the following fields in the next page.
+
+### Code
+
+It’s the locale code, in this case `am`.
+
+### Google Translate code
+
+Google Translate maintains a list of supported locales in its own format. Choose one that matches the locale from [a list of supported locales](https://translate.google.com/intl/en/about/languages/) or leave it blank to disable support for Google Translate for this locale.
+
+### Google AutoML model
+
+Set your [Google Cloud AutoML Translation](https://cloud.google.com/translate/) model ID to use the custom translation engine with a trained model. You can find the model ID in [Google Cloud management console](https://console.cloud.google.com/translation/models/list). If the value is not set, Google’s generic machine translation technology is used instead.
+
+### MS translator code
+
+Microsoft Translator maintains a list of supported locales in its own format. Choose one that matches the locale from [a list of supported locales](https://docs.microsoft.com/azure/cognitive-services/Translator/language-support) or leave it blank to disable support for Microsoft Translator for this locale.
+
+### MS terminology code
+
+Microsoft Terminology maintains a list of supported locales in its own format. Choose one that matches the locale from a list provided below the field or leave it blank to disable support for Microsoft Terminology for this locale.
+
+### Name
+
+It’s the language name, in this case `Amharic`.
+
+### Plural rule
+
+It’s the GetText plural rule. This [document](http://docs.translatehouse.org/projects/localization-guide/en/latest/l10n/pluralforms.html) has plural rules for several languages. For example, for Amharic it would be:
+
+```
+nplurals=2; plural=(n > 1);
+```
+
+As explained in the note below the field, you only need to put the last part in the field:
+
+```
+(n > 1)
+```
+
+### CLDR Plurals
+
+You need to find the locale on [CLDR](https://unicode-org.github.io/cldr-staging/charts/latest/supplemental/language_plural_rules.html). For Amharic, there are only two **cardinal** plural forms listed: one, other.
+
+The mapping is:
+
+```
+0 -> zero
+1 -> one
+2 -> two
+3 -> few
+4 -> many
+5 -> other
+```
+
+For Amharic you will need to set the field as `1,5`, separating the available forms with a comma (no spaces).
+
+Irish (ga-IE), for example, has all of them except for 0, so it will be `1,2,3,4,5`.
+
+### Script
+
+The script used by this locale. Find it in [CLDR Languages and Scripts](http://www.unicode.org/cldr/charts/latest/supplemental/languages_and_scripts.html).
+
+### Direction
+
+Writing direction of the script. Set to `right-to-left` if `rtl` value for the locale script is set to `YES` in [CLDR scriptMetadata.json](https://github.com/unicode-cldr/cldr-core/blob/master/scriptMetadata.json).
+
+### Population
+
+This represents the number of native speakers. There are two ways to get this information from CLDR.
+
+#### Using a script
+
+Python needs to be available on the method to use this system: save [this file](https://raw.githubusercontent.com/mozilla-l10n/documentation/main/scripts/cldr_population.py) on your computer as `cldr_population.py` and run it as `python cldr_population.py LOCALE_CODE`.
+
+For example, this is the output of the script when checking data for `sl`:
+
+```
+$ python scripts/cldr_population.py sl
+
+Adding HU: 4937 (0.05% of 9874780)
+Adding IT: 105412 (0.17% of 62007500)
+Adding SI: 1720886 (87% of 1978030)
+Adding AT: 32233 (0.37% of 8711770)
+--------
+Territories: AT, HU, IT, SI
+Population: 1863468
+--------
+```
+
+#### Manual process
+
+Find the locale code in [CLDR territoryInfo.json](https://github.com/unicode-cldr/cldr-core/blob/master/supplemental/territoryInfo.json) and multiply its `_populationPercent` with the territory `_population`. Repeat if multiple occurrences of locale code exist and sum products.
+
+At this point click **SAVE** in the bottom right corner to save and create the new locale. The "Terminology" project should appear automatically under the new team’s page — in this case at https://pontoon.mozilla.org/am/
+
+### Access key localization
+
+In software, access keys allow users to activate a menu command using their keyboard, and they’re displayed as an underlined character in the menu label. Some locales, especially those using a script different than Latin (Chinese, Japanese, etc.), don’t localize access keys, and use the same character as English. In this case, the access key will be appended to the label as an underlined character between parentheses.
+
+Pontoon can recognize an access key attribute in Fluent strings, and provide translators with a dynamic UI to select one of the characters available in the localized label.
+
+When the checkbox is selected (default), Pontoon will leave the access key field empty, and show the dynamic UI when translating. For pretranslation, it will use the first character from the pretranslated label.
+
+When the checkbox is deselected, Pontoon will automatically use the same access key as the source string, for both manual translation and pretranslation.
diff --git a/documentation/docs/admin/adding-new-project.md b/documentation/docs/admin/adding-new-project.md
new file mode 100644
index 0000000000..0dc28bb445
--- /dev/null
+++ b/documentation/docs/admin/adding-new-project.md
@@ -0,0 +1,114 @@
+# Adding a New Project
+
+The following page describes how to make your projects localizable with your Pontoon instance.
+
+Pontoon specializes in using version control systems as the source and store of localizable strings. While [internal Pontoon DB](adding-new-db-project.md) can be used for that purpose as well, steps below assume you store strings in a [GitHub repository](https://help.github.com/en/articles/create-a-repo).
+
+## Verify that the project is properly localizable
+
+Before you can set up a new project in Pontoon:
+
+1. Ensure your project works with one of the supported l10n frameworks:
+ * `.dtd`
+ * `.ftl` (Fluent)
+ * `.ini`
+ * `.json` (WebExtensions)
+ * `.json` (key-value)
+ * `.po` (Gettext)
+ * `.properties`
+ * `.xliff`
+ * `.xml` (Android)
+
+2. Extract localizable strings into resource files.
+
+3. Push resource files to your GitHub repository.
+
+4. Make sure your Pontoon instance has write access to your repository ([see this document](https://mozilla-l10n.github.io/documentation/misc/creating_new_repository.html#add-collaborators)).
+
+!!! tip "Tip"
+ The recommended way for that is to create a dedicated GitHub account for your Pontoon instance, [add it as a collaborator](https://help.github.com/en/articles/inviting-collaborators-to-a-personal-repository) to your repository, and set `SSH_KEY` and `SSH_CONFIG`.
+
+It’s important to also check the files for localization issues before exposing them to localizers: unclear strings, lack of localization comments, missing plural forms are some of the things to check.
+
+## Folder structure
+
+To let Pontoon discover your localizable files, you'll either need to specify paths in the [project configuration file](https://moz-l10n-config.readthedocs.io/en/latest/fileformat.html) or strictly follow the file and folder structure as expected by Pontoon:
+
+1. Locale folders (including source locale) must be located at the same nesting level of the directory tree. You may want to put all locale folders under a `locales` folder.
+1. Source locale needs to be called `templates`, `en-US`, `en-us` or `en`. If multiple folders with such name exist in the repository and contain files in a supported file format, the first one will be used.
+1. Locale folder names must always match locale identifiers used by Pontoon. If your application requires different identifiers, you can try creating symbolic links to locale folders.
+1. Locale code must not be part of the file name.
+
+Correct pattern:
+
+ locales/{locale_code}/path/to/file.extension
+
+Incorrect pattern:
+
+ locales/{locale_code}/path/to/file.{locale_code}.extension
+
+!!! note "Gettext .po files"
+ For Gettext files, you will need to ensure that `.po` files are included in the repository for each target locale for which they are to be translated (these files may be initially empty). For all other supported formats, Pontoon will automatically add files for each locale when it is translated.
+
+## Create the project
+
+Access Pontoon’s [admin console](https://pontoon.mozilla.org/admin/) and click **ADD NEW PROJECT**.
+
+The new project will appear in the [public list of Projects](https://pontoon.mozilla.org/projects/) only after the next sync cycle.
+
+* Name: name of the repository (it will be displayed in Pontoon’s project selector).
+* Slug: used in URLs, will be generated automatically based on the repository’s name.
+* Locales:
+
+ * Select at least one locale. To make things faster it’s possible to copy supported locales from an existing project.
+ * The *Read-only* column can be used to add languages in read-only mode. In this way, their translations will be available to other languages in the LOCALES tab when translating, but it won’t be possible to change or submit translations directly in Pontoon.
+ * You can uncheck the `Locales can opt-in` checkbox to prevent localizers from requesting this specific project.
+
+* Repositories: select the type of repository and URL. Make sure to use SSH to allow write access. For example, if the repository is `https://github.com/meandavejustice/min-vid`, the URL should be `git@github.com:meandavejustice/min-vid.git`. You can use the *Clone or download* button in the repository page on GitHub, making sure that *Clone with SSH* is selected.
+* Leave the `Branch` field empty, unless developers asked to commit translations in a specific branch instead of the default one (usually `main` or `master`).
+* Download prefix or path to TOML file: a URL prefix for downloading localized files. For GitHub repositories, select any localized file on GitHub, click `Raw` and replace locale code and the following bits in the URL with `{locale_code}`. For example, if the link is `https://raw.githubusercontent.com/bwinton/TabCenter-l10n/master/locales/en-US/addon.properties`, the field should be set to `https://raw.githubusercontent.com/bwinton/TabCenter-l10n/master/locales/{locale_code}`. If you use a project configuration file, you need to provide the path to the raw TOML file on GitHub, e.g. `https://raw.githubusercontent.com/mozilla/common-voice/main/l10n.toml`.
+* Public Repository Website: displayed on dashboards. E.g. `https://github.com/meandavejustice/min-vid`. Pontoon will try to prefill it after you enter Repository URL.
+* Project info: provide some information about the project to help localizers with context or testing instructions. HTML is supported, so you can add external links. For example:
+
+```HTML
+Localization for the Min Vid add-on.
+```
+
+* Internal admin notes: use them e.g. for developer contacts and information that other PMs will find useful when covering for you.
+* Deadline: if available, enter project deadline in the YYYY-MM-DD format.
+* Priority: select priority level from one of the 5 levels available (Lowest, Low, Normal, High, Highest).
+* Contact: select the L10n driver in charge of the project, probably yourself.
+* External Resources: provide links to external resources like l10n preview environment. You need to enter the name and the URL for each resource. You can also pick one of the predefined names: Development site, Production site, Development build, Production build, Screenshots, Language pack.
+* Visibility: determines who can access the project. Pontoon supports the following visibility types:
+
+ * private (default) - only administrators can access the project.
+ * public - the project is visible for everyone.
+
+* Pretranslation: see the [document dedicated to pretranslation](managing-pretranslation.md).
+
+Click **SAVE PROJECT** at the bottom of the page, then click **SYNC** to run a test sync. In the [Sync log](https://pontoon.mozilla.org/sync/log/) you should be able to see if it succeeded or failed. If all went well, the new project will appear in the [public list of Projects](https://pontoon.mozilla.org/projects/).
+
+**IMPORTANT**
+
+* The repository must include at least one file for one of the locales. If necessary, you will need to manually create it (it can be empty).
+* Once you verify the project works as expected, enable it for the general audience by setting Visibility to Public.
+
+### Tags
+
+Tags can be used in a project to logically group resources, assigning them a priority. To enable tags for a project, check *Tags enabled* and save the project.
+
+For each tag, it’s possible to define:
+
+* *Name*: it will be displayed in project (e.g. `/projects/firefox/tags/`) and localization dashboards (e.g. `/it/firefox/tags/`), but also in search filters.
+* *Slug*: used in URLs for tag dashboards, e.g. `/projects/firefox/tags/devtools/`.
+* *Priority*: like for a project, it’s possible to select a priority level from one of the 5 levels available (Lowest, Low, Normal, High, Highest).
+
+
+
+Once you’ve created a new tag, you need to save the project in order to be able to manage the resources associated to the tag itself, using the button highlighted in green.
+
+### Resource deadline
+
+Like for a project, it’s possible to set a deadline for a Resource.
+
+Go to the [resource section](https://pontoon.mozilla.org/a/base/resource/) of the admin panel, then type the name of your project (e.g. `engagement`) and hit `Enter`. All the resources for your project should appear. Click on the one you want to edit, set the deadline in the `Deadline` field, then click `SAVE`.
diff --git a/documentation/docs/admin/adding-terminology.md b/documentation/docs/admin/adding-terminology.md
new file mode 100644
index 0000000000..0c07e0a580
--- /dev/null
+++ b/documentation/docs/admin/adding-terminology.md
@@ -0,0 +1,22 @@
+# Adding New Terminology
+
+To add new terms to Pontoon, access Django’s admin interface at `https://pontoon.mozilla.org/a/` (note that this is not the usual admin interface), then follow the steps below.
+
+Find and click `Terms` on the navigation pane on the left. Check on the following page to make sure a term does not already exist by searching in the search field near the top.
+
+To add a new term, click `ADD TERM +`. The next page will have the following fields:
+
+* Text (required): Term you wish to register.
+* Part of speech (required): Select the part of speech that applies to your term. In some cases the same string can be registered twice with different parts of speech, e.g. bookmark as a noun (“open your bookmarks”) or as a verb (“bookmark this website”).
+* Definition: Meaning of the term, or explanation of what the term is.
+* Usage: Example usage of the term.
+* Notes: Any other notes or context that could be relevant.
+* Case sensitive: Select if the term should only match when case matches.
+* Do not translate: Select if the term should not be translated (example brand names like Firefox).
+* Forbidden: Select if this term should not be used.
+
+Once the necessary information has been filled out, click one of the three save options `Save and add another`, `Save and continue editing`, or `SAVE` to register the term to Pontoon.
+
+This term will automatically populate in the terminology projects for all locales for translation, and will also appear in the `TERMS` pane of the translation UI when it appears in a string.
+
+Note that only the following fields are displayed in Pontoon as a localization comment for the term: part of speech, definition, usage.
diff --git a/documentation/docs/admin/index.md b/documentation/docs/admin/index.md
new file mode 100644
index 0000000000..3cd3725b15
--- /dev/null
+++ b/documentation/docs/admin/index.md
@@ -0,0 +1,60 @@
+---
+hide:
+ - toc
+---
+
+# Admin Guide
+
+This guide covers administrative tasks in Pontoon — managing projects, locales, users, and communication tools.
+
+!!! note
+ The screenshots in this documentation use the dark theme, but a light theme is also available in your [profile settings](../localizer/users.md).
+
+## Sections
+
+
+
+- :material-folder-plus: **[Adding a New Project](adding-new-project.md)**
+
+ How to set up a standard VCS-backed project in Pontoon, including repository configuration, locale selection, tags, and deadlines.
+
+- :material-calendar-clock: **[Adding a New DB Project](adding-new-db-project.md)**
+
+ How to create database-backed projects for newsletters, campaigns, and surveys — no VCS required.
+
+- :material-translate: **[Adding a New Locale](adding-new-locale.md)**
+
+ How to add a new language/locale to Pontoon, including machine translation setup and plural rules.
+
+- :material-robot: **[Managing Pretranslation](managing-pretranslation.md)**
+
+ How to enable automated pretranslation for a project and train custom Google AutoML models.
+
+- :material-message-text: **[Messaging Center](messaging-center.md)**
+
+ How to send targeted emails and in-app notifications to contributors.
+
+- :material-file-edit: **[Renaming a Localization File](renaming-file.md)**
+
+ Steps to rename a resource file without losing translation history.
+
+- :material-pencil: **[Renaming a Project](renaming-project.md)**
+
+ Steps to safely rename a project slug and update references.
+
+- :material-account-multiple: **[Managing Users](managing-users.md)**
+
+ How to deactivate or remove user accounts.
+
+- :material-book-alphabet: **[Adding Terminology](adding-terminology.md)**
+
+ How to add terms to the Pontoon glossary/terminology project.
+
+
+
+## Accessing the admin console
+
+The Pontoon admin console is available at `/admin/` (e.g., `pontoon.mozilla.org/admin/`). Django's standard admin interface is at `/a/`.
+
+!!! info
+ Only Administrators have access to the admin console. Changes made here affect all users and projects.
diff --git a/documentation/docs/admin/managing-pretranslation.md b/documentation/docs/admin/managing-pretranslation.md
new file mode 100644
index 0000000000..2718add239
--- /dev/null
+++ b/documentation/docs/admin/managing-pretranslation.md
@@ -0,0 +1,37 @@
+# Managing Pretranslation
+
+## Opt-in guidelines to enable new locales
+
+See [this page](https://mozilla-l10n.github.io/localizer-documentation/tools/pretranslation.html#opt-in-guidelines) for the opt-in guidelines.
+
+## Enabling pretranslation in a project
+
+Access Pontoon’s [admin console](https://pontoon.mozilla.org/admin/), and select the project: at the bottom of the page there is a section dedicated to *Pretranslation*.
+
+**IMPORTANT**: if this is the first project for a locale, the first step is to [train and set up the custom machine translation model](#train-and-set-up-a-custom-machine-translation-model) in Google AutoML Translation.
+
+Use the checkbox `PRETRANSLATION ENABLED` to enable the feature for the project, then move the requested locales from the `Available` list to `Chosen`. Clicking the `PRETRANSLATE` button will pretranslate immediately all missing strings in enabled locales, otherwise pretranslation will run automatically as soon as new strings are added to the project.
+
+## Train and set up a custom machine translation model
+
+To improve performance of the machine translation engine powering the pretranslation feature, custom machine translation models are trained for each locale using Pontoon’s translation memory. That results in better translation quality than what’s provided by the generic machine translation engine.
+
+To create a custom translation model, first go to the [team page](https://mozilla-l10n.github.io/localizer-documentation/tools/pontoon/teams_projects.html#team-page) of the locale you are creating a custom translation model for and download its [translation memory file](https://mozilla-l10n.github.io/localizer-documentation/tools/pontoon/translate.html#downloading-and-uploading-translations). Next, go to the [Google Cloud console](https://console.cloud.google.com/translation/datasets?project=moz-fx-pontoon-prod) (requires permission) and follow these instructions — in case of doubt, consult the [official instructions](https://cloud.google.com/translate/automl/docs/create-machine-translation-model).
+
+The first step is to create a translation dataset. In the `Datasets` panel, select `CREATE DATASET`:
+
+* For the `Dataset name`, follow the pattern used by existing datasets: `dataset_LOCALE_YYYY_MM_DD` (e.g. `dataset_pt_BR_2023_09_20`, note that `-` is not allowed).
+* Select the `Translate from…` language (`English (EN)`) and the `Translate to…` language (e.g. `Portuguese (PT)` for `pt-BR`).
+* Click `CREATE`.
+
+This operation will take a few seconds. At the end, an empty dataset with the selected name will be available in the list, with `0` in the `Total pairs` column. It’s now time to import Pontoon’s translation memory and train the model:
+
+* Click the dataset, then navigate to the `IMPORT` tab.
+* Use `SELECT FILES` to select the downloaded TMX file from your device.
+* Click `BROWSE` in the `Destination on Cloud Storage` field and select `pontoon-prod-model-data-c1107144`.
+* Click `CONTINUE` to start the import process. The import process will take a few minutes (it’s possible to close this window and return later to the list of datasets, when completed the `Status` column will say `Success: ImportData`).
+* Once the import is completed, navigate to the `TRAIN` tab and click `START TRAINING`.
+
+Note that creating the model is a background job which takes a few hours (when completed the `Status` column will say `Success: CreateModel`), and models for at most 4 locales can be trained concurrently. When the model is created, store its name (usually starting with `NM`, followed by a series of alphanumeric characters) under *Google automl model* in the [Django’s admin interface](https://pontoon.mozilla.org/a/) of the locale.
+
+From that point on, Machinery will start using the custom machine translation model instead of the generic one and you’ll be set to enable pretranslation for the locale.
diff --git a/documentation/docs/admin/managing-users.md b/documentation/docs/admin/managing-users.md
new file mode 100644
index 0000000000..722b571f50
--- /dev/null
+++ b/documentation/docs/admin/managing-users.md
@@ -0,0 +1,28 @@
+# Managing Users
+
+## Deactivating users
+
+Deactivating a user prevents them from logging in but preserves their contribution history and attribution in translation records.
+
+1. Access Django's admin interface at `/a/`.
+2. Click **Users** and search for the user.
+3. Uncheck the **Active** checkbox on the user's record.
+4. Click **Save**.
+
+Deactivation is reversible — you can reactivate the user by checking **Active** again.
+
+## Removing users
+
+Removing a user **permanently deletes** their account. This is irreversible and should only be done when strictly necessary (e.g., for GDPR/privacy requests).
+
+1. Access Django's admin interface at `/a/`.
+2. Click **Users** and search for the user.
+3. Select the user and choose **Delete selected users** from the action dropdown.
+4. Confirm the deletion.
+
+!!! danger
+ Deleting a user is permanent. Their username may be replaced with an anonymized placeholder in historical translation records.
+
+## Adjusting permissions
+
+To change a user's role (Contributor, Translator, Team Manager), use the **Permissions** tab on the relevant Team page. See [User Accounts & Settings](../localizer/users.md#managing-permissions-team-managers) for details.
diff --git a/documentation/docs/admin/messaging-center.md b/documentation/docs/admin/messaging-center.md
new file mode 100644
index 0000000000..c7824c8a92
--- /dev/null
+++ b/documentation/docs/admin/messaging-center.md
@@ -0,0 +1,58 @@
+# Messaging Center
+
+Pontoon allows you to send emails and in-app notifications to contributors, with advanced filtering options.
+To access the Messaging Center, click [Messaging](https://pontoon.mozilla.org/messaging/) in the page header when logged in as Administrator.
+
+## Message type
+
+Once in the Messaging Center, you will be able to choose your message type at the top of the page. You can choose to send it as a `Notification`, an `Email`, or both (by selecting both types).
+
+By default, emails will only be sent to users who have opted in to `News and updates` in their settings. However, if the message is considered transactional (e.g. an email about a password reset) then the `Transactional` option can be selected and emails will also be sent to users who have not opted in to email communication.
+
+Note: Notifications sent via Messaging Center are not included in Notification email digests.
+
+## Message content
+
+Next, enter your message using the Subject and Body fields. Markdown is supported for advanced formatting, such as creating links.
+
+## Choosing recipients
+
+You can send messages to a wide range of targeted groups by applying precise filters.
+
+### Filter by user role
+
+Select whether you’d like to send your message to Managers, Translators, Contributors, or all of them.
+
+### Filter by locale
+
+Checking the `Filter by Locale` checkbox opens the locale selector. You can choose which locales to include by moving them from the `Available` column on the left to the `Chosen` column on the right. You can also use the `MOVE ALL` options to move all locales from one column to the other.
+
+### Filter by project
+
+Checking the `Filter by Project` checkbox opens the project selector. You can choose which projects to include by moving them from the `Available` column on the left to the `Chosen` column on the right. You can also use the `MOVE ALL` options to move all projects from one column to the other.
+
+### Filter by submitted translations
+
+Filters users by the number of translations they have submitted, or when they submitted a translation. Note that submitted translations are counted even if they have not been approved.
+
+You can set a minimum threshold, maximum threshold, start of date range, and/or end of date range for submitted translations. Fields can be left empty (e.g. setting the minimum threshold to 5 and leaving maximum blank will set the filter to those with 5 or more translations).
+
+### Filter by performed reviews
+
+Filter users based on the number of reviews they have conducted, or when they conducted a review.
+
+You can set a minimum threshold, maximum threshold, start of date range, and/or end of date range for reviews conducted. Fields can be left empty (e.g. setting the minimum threshold to 5 and leaving maximum blank will set the filter to those with 5 or more reviews).
+
+### Filter by last login
+
+Filter contributors based on their last login activity.
+
+You can set the start of date range and/or end of date range. Fields can be left empty (e.g. setting just the `From` field will search for users who have logged in on the specified day or later.)
+
+## Reviewing and sending messages
+
+Click `REVIEW MESSAGE` at the bottom of the page to review your message content, recipients, and selected message type. You will have the option to either return to editing, send the message to yourself (to view the actual rendered notification or email), or send to recipients.
+
+The `SEND TO * RECIPIENTS` button will display the number of users who will receive the message. Review contents of the page carefully and if everything looks okay, complete sending the messages by clicking the button.
+
+A confirmation will appear at the top of the page once the messages have been sent out.
diff --git a/documentation/docs/admin/renaming-file.md b/documentation/docs/admin/renaming-file.md
new file mode 100644
index 0000000000..dc041c5e5e
--- /dev/null
+++ b/documentation/docs/admin/renaming-file.md
@@ -0,0 +1,17 @@
+# Renaming a Localization File
+
+In some cases, project owners will want to rename a file for clarity, or for technical reasons. If it’s only done in the VCS repository, the file will be imported again and you will lose attribution, pending suggestions and history. Since this is a special case, we can work around this and rename the file in Pontoon while keeping existing data (translations, suggestions, attribution, history). The process is not complicated, but it has to be highly coordinated.
+
+## Get a Pull Request ready
+
+Either you or the project owners will get a Pull Request ready that renames the file for all locales. Using a script is recommended as you will need to generate the patch not too long before the next steps to avoid conflicts.
+
+## Rename the resource in Pontoon admin panel
+
+Wait for the current Pontoon sync cycle to end, and make sure you are already logged into Pontoon admin, then merge the Pull Request.
+
+As soon as the Pull Request is merged, go to the [resource section](https://pontoon.mozilla.org/a/base/resource/) of the admin panel, then type the name of your project (e.g. `thimble`) and hit `Enter`. All the resources for your project should appear. Click on the one you want to rename, and in the `path` field, for instance rename `messages.properties` into `server.properties` then click `SAVE`.
+
+It is crucial to do this step **before** the next sync cycle, otherwise the process won’t be effective.
+
+After the next sync, open the file for one of the locales, you should be able to see all the existing data.
diff --git a/documentation/docs/admin/renaming-project.md b/documentation/docs/admin/renaming-project.md
new file mode 100644
index 0000000000..dbfd3ff45b
--- /dev/null
+++ b/documentation/docs/admin/renaming-project.md
@@ -0,0 +1,12 @@
+# Renaming a Project
+
+You need to think carefully on the name when setting up a new project. This is because when a new project is set up, a corresponding slug is automatically generated. Though rare, sometimes a project needs to be renamed because the product name has changed or for some other reasons. To rename it, go to the project Admin page, update the `Name` field and click the `SAVE PROJECT` button. This won't cause any interruption for those in the middle of their work in Pontoon. Do send a communication on the name change to the communities.
+
+A slug is the part of a URL that identifies a page in human-readable keywords. It is usually the end part of the URL.
+There is no need to change the `Slug` field to make it match the revised project name. The reasons are:
+
+* A slug is a unique ID to the project. It doesn’t have to match the project name 100%.
+* Once a slug is claimed, a future project name can’t reuse it, so there is no chance of two projects sharing the same slug.
+* Changing the slug could cause confusion to Pontoon users who bookmarked the project with the old URL. They will run into issue when launching the project through the bookmark. They will find the project in Pontoon eventually but this is an avoidable annoyance.
+
+**Never create a new project** for the purpose of changing the project name. This would lose all attribution for existing translation, metadata like comments, and unreviewed suggestions.
diff --git a/documentation/docs/assets/admin/manage_tags_resources.png b/documentation/docs/assets/admin/manage_tags_resources.png
new file mode 100644
index 0000000000..99ecdfd5c3
Binary files /dev/null and b/documentation/docs/assets/admin/manage_tags_resources.png differ
diff --git a/documentation/docs/assets/localizer/notifications/notifications_dropdown.png b/documentation/docs/assets/localizer/notifications/notifications_dropdown.png
new file mode 100644
index 0000000000..e52b41c06e
Binary files /dev/null and b/documentation/docs/assets/localizer/notifications/notifications_dropdown.png differ
diff --git a/documentation/docs/assets/localizer/profile/activity_graph.png b/documentation/docs/assets/localizer/profile/activity_graph.png
new file mode 100644
index 0000000000..6ea4fefdb9
Binary files /dev/null and b/documentation/docs/assets/localizer/profile/activity_graph.png differ
diff --git a/documentation/docs/assets/localizer/profile/approval_graph.png b/documentation/docs/assets/localizer/profile/approval_graph.png
new file mode 100644
index 0000000000..676e3da50b
Binary files /dev/null and b/documentation/docs/assets/localizer/profile/approval_graph.png differ
diff --git a/documentation/docs/assets/localizer/profile/badges.png b/documentation/docs/assets/localizer/profile/badges.png
new file mode 100644
index 0000000000..6e480ca34c
Binary files /dev/null and b/documentation/docs/assets/localizer/profile/badges.png differ
diff --git a/documentation/docs/assets/localizer/search/entity_translations.png b/documentation/docs/assets/localizer/search/entity_translations.png
new file mode 100644
index 0000000000..0296e14724
Binary files /dev/null and b/documentation/docs/assets/localizer/search/entity_translations.png differ
diff --git a/documentation/docs/assets/localizer/search/entity_translations_source_string.png b/documentation/docs/assets/localizer/search/entity_translations_source_string.png
new file mode 100644
index 0000000000..2d482a55d6
Binary files /dev/null and b/documentation/docs/assets/localizer/search/entity_translations_source_string.png differ
diff --git a/documentation/docs/assets/localizer/search/entity_translations_translation_list.png b/documentation/docs/assets/localizer/search/entity_translations_translation_list.png
new file mode 100644
index 0000000000..5bc63c7ff8
Binary files /dev/null and b/documentation/docs/assets/localizer/search/entity_translations_translation_list.png differ
diff --git a/documentation/docs/assets/localizer/search/translation_search.png b/documentation/docs/assets/localizer/search/translation_search.png
new file mode 100644
index 0000000000..183e09a2f6
Binary files /dev/null and b/documentation/docs/assets/localizer/search/translation_search.png differ
diff --git a/documentation/docs/assets/localizer/search/translation_search_search_options.png b/documentation/docs/assets/localizer/search/translation_search_search_options.png
new file mode 100644
index 0000000000..07b7316541
Binary files /dev/null and b/documentation/docs/assets/localizer/search/translation_search_search_options.png differ
diff --git a/documentation/docs/assets/localizer/search/translation_search_search_results.png b/documentation/docs/assets/localizer/search/translation_search_search_results.png
new file mode 100644
index 0000000000..9f3e83c339
Binary files /dev/null and b/documentation/docs/assets/localizer/search/translation_search_search_results.png differ
diff --git a/documentation/docs/assets/localizer/teams-projects/localization_page_header.png b/documentation/docs/assets/localizer/teams-projects/localization_page_header.png
new file mode 100644
index 0000000000..0c9b652b6a
Binary files /dev/null and b/documentation/docs/assets/localizer/teams-projects/localization_page_header.png differ
diff --git a/documentation/docs/assets/localizer/teams-projects/page_flow.png b/documentation/docs/assets/localizer/teams-projects/page_flow.png
new file mode 100644
index 0000000000..39b90505da
Binary files /dev/null and b/documentation/docs/assets/localizer/teams-projects/page_flow.png differ
diff --git a/documentation/docs/assets/localizer/teams-projects/project_hover.png b/documentation/docs/assets/localizer/teams-projects/project_hover.png
new file mode 100644
index 0000000000..1872d38ec7
Binary files /dev/null and b/documentation/docs/assets/localizer/teams-projects/project_hover.png differ
diff --git a/documentation/docs/assets/localizer/teams-projects/project_page_header.png b/documentation/docs/assets/localizer/teams-projects/project_page_header.png
new file mode 100644
index 0000000000..eefbe78e96
Binary files /dev/null and b/documentation/docs/assets/localizer/teams-projects/project_page_header.png differ
diff --git a/documentation/docs/assets/localizer/teams-projects/request_locale.png b/documentation/docs/assets/localizer/teams-projects/request_locale.png
new file mode 100644
index 0000000000..c9328ee5ee
Binary files /dev/null and b/documentation/docs/assets/localizer/teams-projects/request_locale.png differ
diff --git a/documentation/docs/assets/localizer/teams-projects/request_pretranslation.png b/documentation/docs/assets/localizer/teams-projects/request_pretranslation.png
new file mode 100644
index 0000000000..03ec5f0acc
Binary files /dev/null and b/documentation/docs/assets/localizer/teams-projects/request_pretranslation.png differ
diff --git a/documentation/docs/assets/localizer/teams-projects/request_project.png b/documentation/docs/assets/localizer/teams-projects/request_project.png
new file mode 100644
index 0000000000..331def27d7
Binary files /dev/null and b/documentation/docs/assets/localizer/teams-projects/request_project.png differ
diff --git a/documentation/docs/assets/localizer/teams-projects/team_page_header.png b/documentation/docs/assets/localizer/teams-projects/team_page_header.png
new file mode 100644
index 0000000000..7fa672f8dc
Binary files /dev/null and b/documentation/docs/assets/localizer/teams-projects/team_page_header.png differ
diff --git a/documentation/docs/assets/localizer/teams-projects/tm_tab.png b/documentation/docs/assets/localizer/teams-projects/tm_tab.png
new file mode 100644
index 0000000000..279096d183
Binary files /dev/null and b/documentation/docs/assets/localizer/teams-projects/tm_tab.png differ
diff --git a/documentation/docs/assets/localizer/translate/activate_suggest.png b/documentation/docs/assets/localizer/translate/activate_suggest.png
new file mode 100644
index 0000000000..4c2d8e7957
Binary files /dev/null and b/documentation/docs/assets/localizer/translate/activate_suggest.png differ
diff --git a/documentation/docs/assets/localizer/translate/approve_button.png b/documentation/docs/assets/localizer/translate/approve_button.png
new file mode 100644
index 0000000000..425842342d
Binary files /dev/null and b/documentation/docs/assets/localizer/translate/approve_button.png differ
diff --git a/documentation/docs/assets/localizer/translate/batch_actions.png b/documentation/docs/assets/localizer/translate/batch_actions.png
new file mode 100644
index 0000000000..40efc93e56
Binary files /dev/null and b/documentation/docs/assets/localizer/translate/batch_actions.png differ
diff --git a/documentation/docs/assets/localizer/translate/check_error.png b/documentation/docs/assets/localizer/translate/check_error.png
new file mode 100644
index 0000000000..b81d2460c0
Binary files /dev/null and b/documentation/docs/assets/localizer/translate/check_error.png differ
diff --git a/documentation/docs/assets/localizer/translate/check_warning.png b/documentation/docs/assets/localizer/translate/check_warning.png
new file mode 100644
index 0000000000..6a162ab81c
Binary files /dev/null and b/documentation/docs/assets/localizer/translate/check_warning.png differ
diff --git a/documentation/docs/assets/localizer/translate/profile_menu.png b/documentation/docs/assets/localizer/translate/profile_menu.png
new file mode 100644
index 0000000000..1d2f2a17a2
Binary files /dev/null and b/documentation/docs/assets/localizer/translate/profile_menu.png differ
diff --git a/documentation/docs/assets/localizer/translate/suggest_button.png b/documentation/docs/assets/localizer/translate/suggest_button.png
new file mode 100644
index 0000000000..0112b28217
Binary files /dev/null and b/documentation/docs/assets/localizer/translate/suggest_button.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/concordance_search.png b/documentation/docs/assets/localizer/translation-workspace/concordance_search.png
new file mode 100644
index 0000000000..6a33264e45
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/concordance_search.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/context.png b/documentation/docs/assets/localizer/translation-workspace/context.png
new file mode 100644
index 0000000000..745e2a3ac5
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/context.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/editing_space_ftl.png b/documentation/docs/assets/localizer/translation-workspace/editing_space_ftl.png
new file mode 100644
index 0000000000..a7e01d102a
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/editing_space_ftl.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/editing_space_ftl_plurals.png b/documentation/docs/assets/localizer/translation-workspace/editing_space_ftl_plurals.png
new file mode 100644
index 0000000000..83a4c32423
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/editing_space_ftl_plurals.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/editing_space_ftl_sourceview.png b/documentation/docs/assets/localizer/translation-workspace/editing_space_ftl_sourceview.png
new file mode 100644
index 0000000000..712758d9cb
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/editing_space_ftl_sourceview.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/editing_space_standard.png b/documentation/docs/assets/localizer/translation-workspace/editing_space_standard.png
new file mode 100644
index 0000000000..c3c8be9477
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/editing_space_standard.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/editing_space_terminology.png b/documentation/docs/assets/localizer/translation-workspace/editing_space_terminology.png
new file mode 100644
index 0000000000..6a78408a29
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/editing_space_terminology.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/filters.png b/documentation/docs/assets/localizer/translation-workspace/filters.png
new file mode 100644
index 0000000000..dfe7b5923f
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/filters.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/filters_multiple.png b/documentation/docs/assets/localizer/translation-workspace/filters_multiple.png
new file mode 100644
index 0000000000..a50c851dfd
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/filters_multiple.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/filters_tags.png b/documentation/docs/assets/localizer/translation-workspace/filters_tags.png
new file mode 100644
index 0000000000..a3ceade854
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/filters_tags.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/llm_dropdown.png b/documentation/docs/assets/localizer/translation-workspace/llm_dropdown.png
new file mode 100644
index 0000000000..58ab3c6906
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/llm_dropdown.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/llm_dropdown_rephrased.png b/documentation/docs/assets/localizer/translation-workspace/llm_dropdown_rephrased.png
new file mode 100644
index 0000000000..0bed716e1f
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/llm_dropdown_rephrased.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/locales.png b/documentation/docs/assets/localizer/translation-workspace/locales.png
new file mode 100644
index 0000000000..9d0ea17fd0
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/locales.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/machinery.png b/documentation/docs/assets/localizer/translation-workspace/machinery.png
new file mode 100644
index 0000000000..47cb5b5a9a
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/machinery.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/main_nav.png b/documentation/docs/assets/localizer/translation-workspace/main_nav.png
new file mode 100644
index 0000000000..974f215e09
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/main_nav.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/mobile_ui.png b/documentation/docs/assets/localizer/translation-workspace/mobile_ui.png
new file mode 100644
index 0000000000..521b511db5
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/mobile_ui.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/options.png b/documentation/docs/assets/localizer/translation-workspace/options.png
new file mode 100644
index 0000000000..a852170e18
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/options.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/pinned_comment.png b/documentation/docs/assets/localizer/translation-workspace/pinned_comment.png
new file mode 100644
index 0000000000..fdf5c82444
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/pinned_comment.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/profile_menu.png b/documentation/docs/assets/localizer/translation-workspace/profile_menu.png
new file mode 100644
index 0000000000..67d035377e
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/profile_menu.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/search_field.png b/documentation/docs/assets/localizer/translation-workspace/search_field.png
new file mode 100644
index 0000000000..b95f8984d7
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/search_field.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/sidebar.png b/documentation/docs/assets/localizer/translation-workspace/sidebar.png
new file mode 100644
index 0000000000..1a01a5d73d
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/sidebar.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/sidebar_expand.png b/documentation/docs/assets/localizer/translation-workspace/sidebar_expand.png
new file mode 100644
index 0000000000..97648258ae
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/sidebar_expand.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/status_banners.png b/documentation/docs/assets/localizer/translation-workspace/status_banners.png
new file mode 100644
index 0000000000..4bf4a0166a
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/status_banners.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/status_overview.png b/documentation/docs/assets/localizer/translation-workspace/status_overview.png
new file mode 100644
index 0000000000..8f32cbb9b5
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/status_overview.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/suggestions_diff.png b/documentation/docs/assets/localizer/translation-workspace/suggestions_diff.png
new file mode 100644
index 0000000000..a402f81592
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/suggestions_diff.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/translation_comments.png b/documentation/docs/assets/localizer/translation-workspace/translation_comments.png
new file mode 100644
index 0000000000..e075f6dcaa
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/translation_comments.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/translation_readonly.png b/documentation/docs/assets/localizer/translation-workspace/translation_readonly.png
new file mode 100644
index 0000000000..9ebb486131
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/translation_readonly.png differ
diff --git a/documentation/docs/assets/localizer/translation-workspace/translation_workspace.png b/documentation/docs/assets/localizer/translation-workspace/translation_workspace.png
new file mode 100644
index 0000000000..a33a9cd104
Binary files /dev/null and b/documentation/docs/assets/localizer/translation-workspace/translation_workspace.png differ
diff --git a/documentation/docs/assets/localizer/users/delete_account.png b/documentation/docs/assets/localizer/users/delete_account.png
new file mode 100644
index 0000000000..5a4f04f2d8
Binary files /dev/null and b/documentation/docs/assets/localizer/users/delete_account.png differ
diff --git a/documentation/docs/assets/localizer/users/permissions_general.png b/documentation/docs/assets/localizer/users/permissions_general.png
new file mode 100644
index 0000000000..1a56859871
Binary files /dev/null and b/documentation/docs/assets/localizer/users/permissions_general.png differ
diff --git a/documentation/docs/assets/localizer/users/permissions_project.png b/documentation/docs/assets/localizer/users/permissions_project.png
new file mode 100644
index 0000000000..b8414656cb
Binary files /dev/null and b/documentation/docs/assets/localizer/users/permissions_project.png differ
diff --git a/documentation/docs/assets/localizer/users/profile_settings.png b/documentation/docs/assets/localizer/users/profile_settings.png
new file mode 100644
index 0000000000..c5271d8ed3
Binary files /dev/null and b/documentation/docs/assets/localizer/users/profile_settings.png differ
diff --git a/documentation/docs/assets/localizer/users/translation_locales.png b/documentation/docs/assets/localizer/users/translation_locales.png
new file mode 100644
index 0000000000..1bbacf87e1
Binary files /dev/null and b/documentation/docs/assets/localizer/users/translation_locales.png differ
diff --git a/documentation/docs/assets/pontoon-logo.svg b/documentation/docs/assets/pontoon-logo.svg
new file mode 100644
index 0000000000..85d323e2f1
--- /dev/null
+++ b/documentation/docs/assets/pontoon-logo.svg
@@ -0,0 +1,6 @@
+
diff --git a/documentation/docs/dev/contributing.md b/documentation/docs/dev/contributing.md
new file mode 100644
index 0000000000..30be1578df
--- /dev/null
+++ b/documentation/docs/dev/contributing.md
@@ -0,0 +1,387 @@
+# Contributing
+
+## Source code
+
+Pontoon source code is available on
+[GitHub](https://github.com/mozilla/pontoon).
+
+## Issues
+
+Our work is tracked in
+[GitHub](https://github.com/mozilla/pontoon/issues).
+
+[Report a new issue](https://github.com/mozilla/pontoon/issues/new){ .md-button }
+
+## Docker
+
+While the front-end (JavaScript) build and tests use the host
+environment for development, the back-end systems (Python/Django,
+databases, etc.) run in Docker containers. For production use, also the
+front-end is built in a container. Thus Pontoon requires fewer things to
+get started and you're guaranteed to have the same server setup as
+everyone else.
+
+If you're not familiar with [Docker](https://docs.docker.com/) and
+[docker-compose](https://docs.docker.com/compose/overview/), it's worth
+reading up on.
+
+## JavaScript setup
+
+For working on the front-end, you need the latest versions of Node.js
+and npm ([installation
+instructions](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)).
+Parts of the front-end use [npm
+workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces), which
+are not supported by earlier npm versions.
+
+## Database
+
+If you have a database dump, you can load it into your PostgreSQL
+database.
+
+Make sure you backup your existing database first:
+
+``` shell
+$ make dumpdb
+```
+
+And then load the dump:
+
+``` shell
+$ make loaddb DB_DUMP_FILE=path/to/my/dump
+```
+
+Note that your database container needs to be running while you do that.
+You can start just the postgresql container by running:
+
+``` shell
+$ docker-compose up -d postgresql
+```
+
+## Interactive shell
+
+If you need to run specific commands, that are not covered by our
+`Makefile`, you can start an interactive
+shell inside a Pontoon container:
+
+``` shell
+$ make shell
+```
+
+`make shell-root` is also available to log
+in as `root`, instead of the default
+`pontoon` user.
+
+## Browser Support
+
+The list of browsers supported by Pontoon is defined in the
+`"browserslist"` entry of the root
+package.json, and contains by default:
+
+``` bash
+Firefox >= 78
+Chrome >= 80
+Edge >= 91
+Safari >= 13.1
+```
+
+## Code style
+
+We use code formatters so that we do not have to fight over code style.
+You are free to write code however you like, because in the end the
+formatter is the one that will format it. We thus don't need to pay
+attention to style during code reviews, and are free from those
+never-ending code style discussions.
+
+To format the Python and the JavaScript code at once you can use:
+
+``` shell
+$ make format
+```
+
+Code formatting is explained in more detail in the following sections.
+
+To run the required linters on the Python and the JavaScript code at
+once you can use:
+
+``` shell
+$ make lint
+```
+
+## Python code conventions
+
+Our Python code is automatically formatted using
+[ruff](https://docs.astral.sh/ruff/). We enforce that in our Continuous
+Integration, so you will need to run ruff on your code before sending it
+for review.
+
+You can run ruff locally either as an [add-on in your code
+editor](https://docs.astral.sh/ruff/integrations/#vs-code-official), or
+as a [git pre-hook
+commit](https://docs.astral.sh/ruff/integrations/#pre-commit).
+Alternatively, you can format your code using:
+
+``` shell
+$ make ruff
+```
+
+In the rare case when you cannot fix an error, use `# noqa` to make the
+linter ignore that error (see
+[documentation](https://docs.astral.sh/ruff/linter/#error-suppression)).
+Note that in most cases, it is better to fix the issues than ignoring
+them.
+
+## JavaScript code conventions
+
+Our JavaScript code is automatically formatted using
+[Prettier](https://prettier.io/docs/en/index.html). We enforce that in
+our Continuous Integration, so you will need to run prettier on your
+code before sending it for review.
+
+You can run prettier locally either as an [add-on in your code
+editor](https://prettier.io/docs/en/editors.html), or as a [git pre-hook
+commit](https://prettier.io/docs/en/precommit.html). Alternatively, you
+can format your code using:
+
+``` shell
+$ make prettier
+```
+
+Additionally, there are linting rules that are defined in our
+`eslint.config.mjs` file. To run the linter, do:
+
+``` shell
+$ make eslint
+```
+
+In the rare case when you cannot fix an eslint error, use
+`// eslint-disable` to make the linter ignore that error. Note that in
+most cases, it is better to fix the issues than ignore them.
+
+For more specifics about the `translate` folder, look at the README.md
+file there.
+
+## Git conventions
+
+The first line is a summary of the commit. It should start with one of
+the following:
+
+ Fix #1234
+
+or:
+
+ #1234
+
+The first, when it lands, will cause the issue to be closed. The second
+one just adds a cross-reference.
+
+After that, the commit should explain *why* the changes are being made
+and any notes that future readers should know for context or be aware
+of.
+
+We follow [The seven rules of a great Git commit
+message](https://chris.beams.io/posts/git-commit/#seven-rules):
+
+1. Separate subject from body with a blank line
+2. Limit the subject line to 50 characters
+3. Capitalize the subject line
+4. Do not end the subject line with a period
+5. Use the imperative mood in the subject line
+6. Wrap the body at 72 characters
+7. Use the body to explain what and why vs. how
+
+## Pull requests
+
+Pull request summary should indicate the issue the pull request
+addresses.
+
+Pull request descriptions should cover at least some of the following:
+
+1. What is the issue the pull request is addressing?
+2. Why does this pull request fix the issue?
+3. How should a reviewer review the pull request?
+4. What did you do to test the changes?
+5. Any steps-to-reproduce for the reviewer to use to test the changes
+
+## Code reviews
+
+Pull requests should be reviewed before merging.
+
+Style nits should be covered by linting as much as possible.
+
+Code reviews should review the changes in the context of the rest of the
+system.
+
+## Python Dependencies
+
+Direct dependencies for Pontoon are distributed across four files:
+
+1. `requirements/default.in`: Running Pontoon in production
+2. `requirements/dev.in`: Development
+3. `requirements/test.in`: Testing
+4. `requirements/lint.in`: Linting
+
+In order to pin and hash the direct and indirect dependencies, we use
+[uv pip compile](https://docs.astral.sh/uv/#the-pip-interface), which
+yields corresponding `*.txt` files. These `*.txt` files contain all
+direct and indirect dependencies, and can be used for installation with
+`uv pip`. After any change to the `*.in` files, you should run the
+following command to update all `requirements/*.txt` files.
+
+``` shell
+$ make requirements
+```
+
+When adding a new requirement, add it to the appropriate
+`requirements/*.in` file. For example, to add the development dependency
+`foobar` version 5, add `foobar==5` to `requirements/dev.in`, and then
+run the command from above.
+
+Once you are done adding, removing or updating requirements, rebuild
+your docker environment:
+
+``` shell
+$ make build-server
+```
+
+If there are problems, it'll tell you.
+
+To upgrade existing dependencies within the given constraints of the
+input files, you can pass options through to the `uv pip compile`
+invocations, i.e.
+
+``` shell
+$ make requirements opts=--upgrade
+```
+
+## Documentation
+
+Documentation for Pontoon is built with [Zensical](https://zensical.org/)
+and is available on `http://localhost:8000/docs/`.
+
+To build the docs, run:
+
+``` shell
+$ make docs
+```
+
+## Running tests
+
+To run the entire test suite, do:
+
+``` shell
+$ make test
+```
+
+To run only the `translate` tests:
+
+``` shell
+$ make test-translate
+```
+
+To run only the Python tests:
+
+``` shell
+$ make pytest
+```
+
+To run specific tests or specify arguments, you'll want to start a shell
+in the test container:
+
+``` shell
+$ make shell
+```
+
+Then you can run tests as you like.
+
+Running all the unittests (make sure you run `./manage.py collectstatic`
+first):
+
+``` shell
+app@...:/app$ pytest
+```
+
+Running a directory of tests:
+
+``` shell
+app@...:/app$ pytest pontoon/base/
+```
+
+Running a file of tests:
+
+``` shell
+app@...:/app$ pytest pontoon/base/tests/test_views.py
+```
+
+## Writing tests
+
+Put your tests in the `tests/` directory of the appropriate app in
+`pontoon/`.
+
+### Mock usage
+
+[Mock](https://docs.python.org/dev/library/unittest.mock.html) is a
+python library for mocks objects. This allows us to write isolated tests
+by simulating services besides using the real ones. Best examples are
+existing tests which admittedly do mocking different depending on the
+context.
+
+Tip! Try to mock in limited context so that individual tests don't
+affect other tests. Use context managers instead of monkey patching
+imported modules.
+
+## Updating Your Local Instance
+
+When changes are merged into the main Pontoon repository, you'll want to
+update your local development instance to reflect the latest version of
+the site. You can use Git as normal to pull the latest changes, but if
+the changes add any new dependencies or alter the database, you'll want
+to install any new libraries and run any new migrations.
+
+If you're unsure what needs to be run, it's safe to just perform all of
+these steps, as they don't affect your setup if nothing has changed:
+
+``` shell
+# Pull the latest code (assuming you've already checked out main).
+git pull origin main
+
+# Install new dependencies or update existing ones.
+uv pip install -U --force -r requirements/default.txt
+
+# Run database migrations.
+python manage.py migrate
+```
+
+## Writing to external repositories from a local instance
+
+[Environment variables](deployment.md#environment-variables) like `SSH_KEY` and
+`SSH_CONFIG` have no effect in a Docker setup.
+
+The `~/.ssh` folder of the host system is
+mapped automatically to the home folder within the container. In order
+to connect to a remote repository via SSH, you need to create a
+passwordless SSH key, and configure
+`~/.ssh/config` accordingly.
+
+Here's an example for GitHub, assuming the private key file is called
+`id_ed25519` (see [GitHub's
+instructions](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account)
+for generating a new key):
+
+```
+Host github.com
+ User YOUR_USERNAME
+ IdentityFile ~/.ssh/id_ed25519
+ StrictHostKeyChecking no
+```
+
+The project's repository will use the format
+`git@github.com:{ORGANIZATION}/{REPOSITORY}.git` for the `URL` field.
+
+An alternative approach for GitHub is to use a [Personal Access Token
+(PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens),
+and set up the project's `URL` as
+`https://` instead of
+`git@`. In this case, the `URL` will need
+to include both the PAT and username, e.g.
+`https://{USER}:{TOKEN}@github.com/{REPOSITORY}`.
diff --git a/documentation/docs/dev/deployment.md b/documentation/docs/dev/deployment.md
new file mode 100644
index 0000000000..09c350584f
--- /dev/null
+++ b/documentation/docs/dev/deployment.md
@@ -0,0 +1,495 @@
+# Deployment
+
+Pontoon is designed to be deployed on Google Cloud Platform. Docker images are built from the [Dockerfile](https://github.com/mozilla/pontoon/blob/main/docker/Dockerfile-mozcloud) and pushed to Google Artifact Registry (GAR) every time changes are merged to the `main` or `dev` branch.
+
+Two Pontoon instances are available on MozCloud - Mozilla's internal developer platform:
+
+* **Production server**: [pontoon.mozilla.org](https://pontoon.mozilla.org/)
+* **Development server**: [pontoon.allizom.org](https://pontoon.allizom.org/)
+
+## Environment Variables
+
+The following is a list of environment variables you'll want to set on the app you create:
+
+`ADMIN_EMAIL`
+Optional. Email address for the `ADMINS` setting.
+
+`ADMIN_NAME`
+Optional. Name for the `ADMINS` setting.
+
+`AUTHENTICATION_METHOD`
+The default value is `django`, which allows you to log in via accounts created using `manage.py shell`.
+Set to `fxa` if you want to use "Mozilla Accounts" (corresponding `FXA_*` settings must be set).
+Set to `github` if you want to use "GitHub" (corresponding `GITHUB_*` settings must be set).
+Set to `gitlab` if you want to use "GitLab" (corresponding `GITLAB_*` settings must be set if required).
+Set to `google` if you want to use "Google" (corresponding `GOOGLE_*`
+settings must be set).
+
+`USE_X_FORWARDED_HOST`
+Optional. If using a reverse proxy, set to True to make django-allauth
+redirect_url work as expected. Default value is
+`False`.
+
+`BADGES_START_DATE`
+Optional. Specifies the start date from which user activities count
+towards badge achievements. This variable should be in `YYYY-MM-DD`
+format.
+
+`BADGES_PROMOTION_THRESHOLDS`
+Optional. A comma-separated list of numeric thresholds for different
+levels of the Community Builder badge.
+
+`BADGES_REVIEW_THRESHOLDS`
+Optional. A comma-separated list of numeric thresholds for different
+levels of the Review Master badge.
+
+`BADGES_TRANSLATION_THRESHOLDS`
+Optional. A comma-separated list of numeric thresholds for different
+levels of the Translation Champion badge.
+
+`BLOCKED_IPS`
+A comma-separated list of IP addresses or IP ranges (expressed using the
+[CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation), e.g. `192.168.1.0/24`)
+to be blocked from accessing the app, for example because they are
+DDoS'ing the server.
+
+`CELERY_ALWAYS_EAGER`
+Controls whether asynchronous tasks (mainly used during sync) are sent
+to Celery or executed immediately and synchronously. Set this to `False`
+on production.
+
+`CELERYD_MAX_TASKS_PER_CHILD`
+Maximum number of tasks a Celery worker process can execute before it’s
+replaced with a new one. Defaults to 20 tasks.
+
+`DATABASE_SSLMODE`
+Optional. Controls if the database needs a secure connection with the
+app. Default value is `True`.
+
+`DEFAULT_FROM_EMAIL`
+Optional. Default email address to send emails from. Default value: `Pontoon `.
+
+`DISABLE_COLLECTSTATIC`
+Disables running `./manage.py collectstatic` during the build. Should be
+set to `1`.
+
+`DJANGO_DEBUG`
+Controls `DEBUG` mode for the site. Should be set to
+`False` in production.
+
+`DJANGO_DEBUG_TOOLBAR`
+Enables Django Debug Toolbar (default: `False`). `DJANGO_DEV` must be
+set to `True`.
+
+`DJANGO_DEV`
+Signifies whether this is a development server or not. Should be
+`False` in production. Adds some additional
+django apps that can be helpful during day to day development.
+
+`EMAIL_HOST`
+SMTP host (default: `smtp.sendgrid.net`).
+
+`EMAIL_HOST_PASSWORD`
+Password for the SMTP connection.
+
+`EMAIL_HOST_USER`
+Username for the SMTP connection (default: `apikey`).
+
+`EMAIL_PORT`
+SMTP port (default: `587`).
+
+`EMAIL_USE_TLS`
+Use explicit TLS for the SMTP connection (default: `True`).
+
+`EMAIL_USE_SSL`
+Use implicit TLS for the SMTP connection (default: `False`).
+
+`EMAIL_CONSENT_ENABLED`
+Optional. Enables Email consent page (default: `False`).
+
+`EMAIL_CONSENT_TITLE`
+Optional, unless `EMAIL_CONSENT_ENABLED` is `True`. Title of the Email
+consent page.
+
+`EMAIL_CONSENT_MAIN_TEXT`
+Optional, unless `EMAIL_CONSENT_ENABLED` is `True`. Main text of the
+Email consent page. You can use that to explain what type of
+communication to expect among other things.
+
+`EMAIL_CONSENT_PRIVACY_NOTICE`
+Optional. Privacy notice on the Email consent page. It's possible to use
+HTML and link to external privacy notice page.
+
+`EMAIL_COMMUNICATIONS_HELP_TEXT`
+Optional. Help text to use under the Email communications checkbox in
+user settings. It allows to explain what type of communication to expect
+and to link to deployment-specific privacy notices among other things.
+
+`EMAIL_COMMUNICATIONS_FOOTER_PRE_TEXT`
+Optional. Text to be shown in the footer of the non-transactional emails
+sent using the Messaging Center, just above the unsubscribe text.
+
+`EMAIL_MONTHLY_ACTIVITY_SUMMARY_INTRO`
+Optional. Custom text to be shown in the Monthly activity summary emails
+after the greeting and before the stats.
+
+`ENABLE_BUGS_TAB`
+Optional. Enables Bugs tab on team pages, which pulls team data from
+bugzilla.mozilla.org. Specific for Mozilla deployments.
+
+`ENABLE_INSIGHTS`
+Optional. Enables Insights pages, which present data that needs to be
+collected by the [Collect Insights](#collect-insights) scheduled job. It is advised to run
+the job at least once before enabling the tab, otherwise the content
+will be empty. See [the
+spec](https://github.com/mozilla/pontoon/blob/HEAD/specs/0108-community-health-dashboard.md)
+for more information.
+
+`GOOGLE_ANALYTICS_KEY`
+Optional. Set your [Google Analytics
+key](https://www.google.com/analytics/) to use Google Analytics.
+
+`GOOGLE_TRANSLATE_API_KEY`
+Optional. Set your [Google Cloud Translation
+API](https://cloud.google.com/translate/) key to use generic machine
+translation engine by Google.
+
+`GOOGLE_AUTOML_PROJECT_ID`
+Optional. Set your [Google Cloud AutoML
+Translation](https://cloud.google.com/translate/) model ID to use custom
+machine translation engine by Google.
+
+`GOOGLE_APPLICATION_CREDENTIALS`
+Optional. Path to a Google Cloud service account JSON key file used by
+Google client libraries for authentication.
+
+`INACTIVE_CONTRIBUTOR_PERIOD`
+Optional. Number of months in which the contributor needs to log in in
+order not to receive the inactive account email. The default value is 6.
+
+`INACTIVE_TRANSLATOR_PERIOD`
+Optional. Number of months in which the locale translator needs to
+submit or review at least one translation in order not to receive the
+inactive account email. The default value is 2.
+
+`INACTIVE_MANAGER_PERIOD`
+Optional. Number of months in which the locale manager needs to submit
+or review at least one translation in order not to receive the inactive
+account email. The default value is 2.
+
+`LOG_TO_FILE`
+Optional. Enables logging to a file (default: `False`). This is useful
+for retaining log data for later analysis or troubleshooting.
+
+`MANUAL_SYNC`
+Optional. Enable Sync button in project Admin.
+
+`MEDIA_ROOT`
+Optional. The absolute path of the "media" folder the projects will be
+cloned into (it is located next to the "pontoon" Python module by
+default).
+
+`MICROSOFT_TRANSLATOR_API_KEY`
+Optional. Set your [Microsoft Translator
+API](http://msdn.microsoft.com/en-us/library/hh454950) key to use
+machine translation by Microsoft.
+
+`MONTHLY_ACTIVITY_SUMMARY_DAY`
+Optional. Integer representing a day of the month on which the Monthly
+activity summary emails will be sent. 1 represents the first day of the
+month. The default value is 1.
+
+`NEW_RELIC_API_KEY`
+Optional. API key for accessing the New Relic REST API. Used to mark
+deploys on New Relic.
+
+`NEW_RELIC_APP_NAME`
+Optional. Name to give to this app on New Relic. Required if you're
+using New Relic.
+
+`NOTIFICATION_DIGEST_DAY`
+Optional. Integer representing a day of the week on which the weekly
+notification digest email will be sent. 0 represents Monday, 6
+represents Sunday. The default value is 4 (Friday).
+
+`ONBOARDING_EMAIL_2_DELAY`
+Optional. The number of days to wait after user registration before
+sending the 2nd onboarding email. The default value is 2.
+
+`ONBOARDING_EMAIL_3_DELAY`
+Optional. The number of days to wait after user registration before
+sending the 3rd onboarding email. The default value is 7.
+
+`OPENAI_API_KEY`
+Optional. Set your `OpenAI API` key to add
+the ability to refine machine translations using ChatGPT.
+
+`PERSONAL_ACCESS_TOKEN_MAX_COUNT`
+Optional. The maximum number of personal access tokens a user can
+create. The default value is 10.
+
+`PRETRANSLATION_API_MAX_CHARS`
+Optional. Specifies the maximum length of input text allowed for
+pretranslation API. The default value is 2048.
+
+`PROJECT_MANAGERS`
+Optional. A list of project manager email addresses to send project
+requests to
+
+`PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION`
+Required. Must be set to `python`. Needed for Google AutoML Translation.
+Learn more on [Protocol Buffers
+Homepage](https://developers.google.com/protocol-buffers/docs/news/2022-05-06#python-updates).
+
+`SECRET_KEY`
+Required. Secret key used for sessions, cryptographic signing, etc.
+
+`SITE_URL`
+Controls the base URL for the site, including the protocol and port.
+Defaults to `http://localhost:8000`, should always be set in production.
+
+`ALLOWED_HOSTS`
+A list of strings representing the host/domain names the site can serve.
+Defaults to `.localhost, 127.0.0.1, [::1]`, should always be set in
+production.
+
+`SECURE_SSL_REDIRECT`
+Optional. If True, redirects all non-HTTPS requests to HTTPS. Default
+value is `True`. Learn more in the [Django
+documentation](https://docs.djangoproject.com/en/5.1/ref/settings/#secure-ssl-redirect).
+
+`CSRF_TRUSTED_ORIGINS`
+Optional. A comma-separated list of trusted origins for unsafe requests.
+It should contain the domains where the app is available. The setting
+also supports subdomains, so you could add `https://*.example.com`, for
+example, to allow access from all subdomains of `example.com`. Default
+value is an empty string. Learn more in the [Django
+documentation](https://docs.djangoproject.com/en/5.1/ref/settings/#csrf-trusted-origins).
+
+`SSH_CONFIG`
+Contents of the `~/.ssh/config` file used when Pontoon connects to VCS
+servers via SSH. Used for disabling strict key checking and setting the
+default user for SSH. For example:
+
+ StrictHostKeyChecking=no
+
+ Host hg.mozilla.org
+ User pontoon@mozilla.com
+
+`SSH_KEY`
+SSH private key to use for authentication when Pontoon connects to VCS
+servers via SSH.
+
+`STATIC_HOST`
+Optional. Hostname to prepend to static resources paths. Useful for
+serving static files from a CDN. Example: `//asdf.cloudfront.net`.
+
+`SUGGESTION_NOTIFICATIONS_DAY`
+Optional. Integer representing a day of the week on which the
+`send_suggestion_notifications` management
+command will run. 0 represents Monday, 6 represents Sunday. The default
+value is 4 (Friday).
+
+`SYNC_TASK_TIMEOUT`
+Optional. Multiple sync tasks for the same project cannot run
+concurrently to prevent potential DB and VCS inconsistencies. We store
+the information about the running task in cache and clear it after the
+task completes. In case of an error, we might never clear the cache, so
+we use SYNC_TASK_TIMEOUT as the longest possible period after which the
+cache is cleared and the subsequent task can run. The value should
+exceed the longest sync task of the instance. The default value is 3600
+seconds (1 hour).
+
+`SYSTRAN_TRANSLATE_API_KEY`
+Optional. Set your [Systran Translate](https://auth.systran.net/oidc/interaction/OcxBMUAbEIkN6tIg1yIcp) API key to use machine translation by Systran.
+
+`TBX_DESCRIPTION`
+Optional. Description to be used in the header of the Terminology (`.TBX`)
+files.
+
+`TBX_TITLE`
+Optional. Title to be used in the header of the Terminology (`.TBX`)
+files.
+
+`THROTTLE_ENABLED`
+Optional. Enables traffic throttling based on IP address (default:
+`False`).
+
+`THROTTLE_MAX_COUNT`
+Optional. Maximum number of requests allowed in
+`THROTTLE_OBSERVATION_PERIOD` (default: `300`).
+
+`THROTTLE_OBSERVATION_PERIOD`
+Optional. A period (in seconds) in which `THROTTLE_MAX_COUNT` requests
+are allowed. (default: `60`). If longer than `THROTTLE_BLOCK_DURATION`,
+`THROTTLE_BLOCK_DURATION` will be used.
+
+`THROTTLE_BLOCK_DURATION`
+Optional. A duration (in seconds) for which IPs are blocked (default:
+`600`).
+
+`TZ`
+Timezone for the dynos that will run the app. Pontoon operates in UTC,
+so set this to `UTC`.
+
+`VCS_SYNC_NAME`
+Optional. Default committer's name used when committing translations to
+version control system.
+
+`VCS_SYNC_EMAIL`
+Optional. Default committer's email used when committing translations to
+version control system.
+
+## Scheduled Jobs
+
+Pontoon requires several scheduled jobs to run regularly.
+
+### Sync Projects
+
+While internal Pontoon DB can be used for storing localizable strings,
+Pontoon specializes in using version control systems for that purpose.
+If you choose this option as well, you'll need to run the following
+scheduled job:
+
+``` bash
+./manage.py sync_projects
+```
+
+It's recommended to run this job at least once an hour. It commits any
+string changes in the database to the remote VCS servers associated with
+each project, and pulls down the latest changes to keep the database in
+sync.
+
+The command supports the following options:
+
+- `--force` -- Consider all version control repository files to have
+ changed.
+- `--no-pull` -- Do not pull new changes for version control
+ repositories.
+- `--no-commit` -- Do not commit and push any new changes to version
+ control.
+
+### Send Deadline Notifications
+
+Pontoon allows you to set deadlines for projects. This job sends
+deadline reminders to contributors of projects when they are due in 7
+days. If 2 days before the deadline project still isn't complete for the
+contributor's locale, notifications are sent again. The command is
+designed to run daily.
+
+``` bash
+./manage.py send_deadline_notifications
+```
+
+### Send Suggestion Notifications
+
+This job sends notifications about newly created unreviewed suggestions
+that were submitted, unapproved or unrejected in the last 7 days.
+Recipients of notifications are users with permission to review them, as
+well as authors of any previous translations or comments of the same
+string. The command is designed to run on a weekly basis.
+
+``` bash
+./manage.py send_suggestion_notifications
+```
+
+### Send Review Notifications
+
+This job sends notifications about newly reviewed (approved or rejected)
+suggestions to the authors of those suggestions. The command is designed
+to run on a daily basis.
+
+``` bash
+./manage.py send_review_notifications
+```
+
+### Send Notification Emails
+
+This job sends notifications in daily and weekly email digests. Daily
+notifications are sent every time the command runs, while weekly
+notifications are sent only on the configured day (e.g., Friday).
+
+``` bash
+./manage.py send_notification_emails
+```
+
+### Send Monthly Activity Emails
+
+This job sends a summary of monthly activity to users via email. It is
+designed to run on a specific day of the month but can be forced to run
+at any time using the `--force` option.
+
+``` bash
+./manage.py send_monthly_activity_emails
+```
+
+### Send Onboarding Emails
+
+Pontoon sends onboarding emails to new users. The first one is sent upon
+registration, while this job sends the 2nd and 3rd email. You can
+configure the number of days to wait before sending the 2nd and 3rd
+emails. The command is designed to run daily.
+
+``` bash
+./manage.py send_onboarding_emails
+```
+
+### Send Inactive Account Emails
+
+This command sends reminder emails to inactive users. Users in different
+roles get different emails based on different activity criteria, which
+can be configured in settings. The command is designed to run daily.
+
+``` bash
+./manage.py send_inactive_account_emails
+```
+
+### Collect Insights
+
+The Insights tab in the dashboards presents data that cannot be
+retrieved from the existing data models efficiently upon each request.
+This job gathers all the required data and stores it in a dedicated
+denormalized data model. The job is designed to run in the beginning of
+the day, every day.
+
+``` bash
+./manage.py collect_insights
+```
+
+### Warm up cache
+
+We cache data for some of the views (e.g. Contributors) for a day. Some
+of them don't get a lot of visits, not even one per day, meaning that
+the visitors of these pages often hit the cold cache. We use this job to
+refresh data in the cache every day, because it changes often. The
+command is designed to run daily.
+
+``` bash
+./manage.py warmup_cache
+```
+
+### Clearing the session store
+
+When a user logs in, Django adds a row to the `django_session` database
+table. If the user logs out manually, Django deletes the row. But if the
+user does not log out, the row never gets deleted.
+
+Django does not provide automatic purging of expired sessions.
+Therefore, it’s your job to purge expired sessions on a regular basis.
+Django provides a clean-up management command for this purpose:
+`clearsessions`. It’s recommended to run this command as a daily cron
+job.
+
+``` bash
+./manage.py clearsessions
+```
+
+### Sync Log Retention
+
+You may also optionally run the `clear_old_sync_logs` management command
+on a schedule to remove sync logs from the database that are over 90
+days old:
+
+``` bash
+./manage.py clear_old_sync_logs
+```
diff --git a/documentation/docs/dev/developer-setup.md b/documentation/docs/dev/developer-setup.md
new file mode 100644
index 0000000000..92fa0b490c
--- /dev/null
+++ b/documentation/docs/dev/developer-setup.md
@@ -0,0 +1,74 @@
+# Developer Setup
+
+The following describes how to set up an instance of the site on your computer for development with Docker.
+
+!!! info "Scope of this document"
+ These installation steps are made for development purposes only. To run Pontoon in the production environment, see the [Deployment](deployment.md) docs.
+
+## Prerequisites
+
+1. Install [Docker](https://docs.docker.com/install/).
+2. Install [latest versions of Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
+3. Install [make](https://www.gnu.org/software/make/) using either your system's package manager (Linux) or Xcode command line developer tools (OSX). On Windows, you can use [MozillaBuild](https://wiki.mozilla.org/MozillaBuild).
+
+## Quickstart
+
+1. Clone the [Pontoon repository](https://github.com/mozilla/pontoon):
+
+ ```
+ $ git clone https://github.com/mozilla/pontoon.git
+ ```
+
+ !!! note "Note"
+ To contribute changes to the project, you will need to [fork](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) the repository under your own GitHub account.
+
+2. From the root of the repository, run:
+
+ ```
+ $ make build
+ ```
+
+ That will install Pontoon's JS dependencies, build the frontend packages, and build the server container.
+
+ !!! tip "Tip"
+ If you want to share your development instance in your local network, set SITE_URL to bind the server to any address you like, e.g. `make build SITE_URL="http://192.168.1.14:8000"`.
+
+3. Run the webapp:
+
+ ```
+ $ make run
+ ```
+
+ !!! note "Note"
+ The first time you run this, the PostgreSQL container needs to do some work before it becomes available to the server container. Hence, the server might not be able to perform things like migrations. You can simply wait for the postgresql container to report that it's ready, then abort the process, then restart it. That should let the server do all its setup as expected.
+
+ Alternatively, you can run `docker-compose up postgresql` and wait until it reports that the database is ready, then stop that and run `make run`.
+
+4. Finally, you need to run some setup steps, while the server is running:
+
+ ```
+ $ make setup
+ ```
+
+ This will ask you to create a superuser, and then will update your Firefox account settings.
+
+The app should now be available at or the custom SITE_URL.
+
+And with that, you're ready to start [Contributing](contributing.md)!
+
+## Installing Docker on Windows
+
+To setup Pontoon for development on Windows Pro/Enterprise/Education, install [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/).
+
+Next, install other prerequisites using a package manager like [Chocolatey](https://chocolatey.org/install). Follow the installation instructions for Windows Powershell (Admin), then run `choco install make git cygwin` to install all packages.
+
+Follow the prompt requests allowing script execution. At the end, verify that packages are available with `make --version` and `git --version`. It should return a version for each command.
+
+Also, you need to disable the config `core.autocrlf` before cloning the Pontoon repository, otherwise all files will use Windows line-endings (CRLF), and docker images will fail to build. To do so, open a Powershell as Admin (right click on the Start Menu, select *Windows Powershell (Admin)*), and run:
+
+git config --system --unset core.autocrlf
+git config --global core.autocrlf false
+
+You can use `git config -l` to verify that the value for `core.autocrlf` is correctly set.
+
+At this point, you can open the *Cygwin64 Terminal* and proceed with the installation (the content of `C:` will be available in `/cygdrive/c`). Once the Docker image is running, Pontoon's instance will be available at `http://localhost:8000`.
diff --git a/documentation/docs/dev/feature-development-process.md b/documentation/docs/dev/feature-development-process.md
new file mode 100644
index 0000000000..5dda87cd52
--- /dev/null
+++ b/documentation/docs/dev/feature-development-process.md
@@ -0,0 +1,111 @@
+# Feature Development Process
+
+Landing a new feature or significant change in Pontoon follows a
+structured yet flexible process. The goal is to ensure high-quality,
+well-considered contributions that align with project priorities and
+community needs.
+
+## Propose the Idea
+
+Anyone can suggest improvements: new features, enhancements to existing
+ones, or feature removals.
+
+- For trivial changes (typos, minor bugfixes), a pull request (PR) alone
+ may suffice—no dedicated issue required.
+- For anything non-trivial, [create a GitHub issue](https://github.com/mozilla/pontoon/issues/new):
+
+ - Clearly describe the problem/opportunity.
+ - Explain the motivation, expected impact, and user value.
+ - Include relevant context (screenshots, use cases, alternatives considered).
+
+## Triage
+
+Core maintainers review new issues and perform triage on a weekly basis
+to assign:
+
+- Type: Bug, Feature, Task.
+- Priority label: P1 (must be fixed immediately) to P5 (valid bug, but
+ you might need to fix it).
+- Labels such as `needs specification` or `needs documentation` if
+ required.
+- Labels for rough time estimate: hours, days, weeks, months, quarters.
+
+The issue is added to the [Pontoon Roadmap GitHub project](https://github.com/orgs/mozilla/projects/220):
+
+- Initially placed in “Needs triage”.
+- Moved to “Ready” once actionable.
+- Kept in “Not ready yet” if more discussion or a spec is needed.
+- High-priority items ready for near-term work move to the top of the
+ “Ready” column.
+- Larger initiatives (estimated to take months or quarters) are always
+ kept in the "Not ready" column before they are split into smaller
+ issues.
+
+## Specification
+
+For medium-to-large features (those affecting UX flows, data models,
+multiple areas, or needing community consensus):
+
+- Draft a specification document in Markdown format and submit it as a
+ PR to the `specs/` folder.
+- Follow the structure seen in the [template](https://github.com/mozilla/pontoon/blob/main/specs/0000-template.md) and the existing specs (problem statement, goals, user stories,
+ proposed solution, impacted areas, risks, alternatives, migration plan
+ if applicable).
+- Get feedback and approval from core team members. For larger specs,
+ it is advisable to use Google Docs for the authoring and review phase,
+ then export the spec as Markdown and publish it in the repository.
+
+Once approved, remove any `needs specification` label and move the issue
+to “Ready” on the Roadmap.
+
+## Implementation
+
+- When ready to begin, assign yourself or get assigned to the issue.
+- The issue will then move to “In Progress” on the Roadmap.
+- Work in a feature branch.
+- Deliver:
+
+ - Clean, complete code.
+ - Unit and integration tests with good coverage.
+ - Any necessary database migrations or data changes.
+
+## Code Review
+
+- Open a pull request targeting the “main” branch.
+- Make sure CI tests pass.
+- Review is requested from core Pontoon team members.
+- Address feedback on code quality, security, performance, test
+ coverage, and best practices.
+- Once approved, the PR is merged.
+- The associated issue is automatically closed and moved to “Done” on
+ the Roadmap.
+
+## Testing
+
+The contributor is primarily responsible for thorough testing.
+
+- Verify the feature behaves as intended.
+- Check for regressions.
+- For larger features, perform extensive testing in the development
+ environment during/after review.
+- Core team may run additional testing.
+
+## Release
+
+Deployments are handled by core maintainers and occur as changes are ready (typically immediately after, no strict cadence).
+
+- Features are first deployed to the [development
+ environment](https://pontoon.allizom.org/) for final validation.
+- Once confirmed stable, they go live on production.
+
+## Documentation & Discoverability
+
+If labeled `needs documentation` or if the change affects users noticeably:
+
+ - Update or add content in the Pontoon documentation.
+
+For major or high-impact features:
+
+ - Core team may add in-app announcements.
+ - The contributor might write a blog post on the [Mozilla L10n
+ blog](https://blog.mozilla.org/l10n/).
diff --git a/documentation/docs/dev/first-contribution.md b/documentation/docs/dev/first-contribution.md
new file mode 100644
index 0000000000..b1dc9f630b
--- /dev/null
+++ b/documentation/docs/dev/first-contribution.md
@@ -0,0 +1,163 @@
+# The Guide to your First Contribution
+
+This document is going to guide you as you discover Pontoon and make
+valuable contributions. It will walk you step by step until you are in a
+position to write code that you can reliably run, test, and send for
+review.
+
+## 1. Make sure it's a good match
+
+Before contributing to an open source project, it is important to make
+sure that the project uses technologies that you know and want to learn
+more about.
+
+Pontoon is a web application, with both back-end and front-end code. The
+two languages we use are **Python** (back-end) and **JavaScript**
+(front-end). On the back-end, we use the **Django** framework. On the
+front-end, we use the **React** framework. To be able to contribute, you
+will want to have knowledge of either Python and Django or JavaScript
+and React. Having experience with both pairs is of course even better!
+
+We use **git** to version our code, and we use **GitHub** to handle pull
+requests and code reviews. Basic knowledge of git is required to be able
+to send your contributions our way.
+
+| Skill | Expected Level | Notes |
+|------------|-----------------|-----------------|
+| git | Basic knowledge | |
+| Python | Some experience | Python 3 |
+| Django | Basic knowledge | |
+| JavaScript | Some experience | ECMAScript 2018 |
+| React | Basic knowledge | |
+
+## 2. Install Pontoon
+
+In order to be able to contribute code to an open source project, you
+first need to be able to run that project on your computer.
+
+The recommended method of installing Pontoon is using Docker and our
+scripts. It is straightforward if your computer is running with Linux or
+macOS, and a tad more difficult for Windows. In any case, follow the
+instructions in our [Developer Setup page](developer-setup.md).
+
+## 3. Populate your database
+
+After installing a tool, it is likely that its database is empty. You
+will need to create some data in order to have things show up in the
+interface.
+
+Once Pontoon is installed and you have it running, you will want to
+create some data so that you can play with it, and test it in action.
+You can create any kind of data you want, of course, but to make it
+easier we have a special git repository that we made for testing
+Pontoon. Here are the steps to add that project to your Pontoon
+instance:
+
+1. Log in to your local instance with the superuser account you created
+ during the previous step.
+2. Click the avatar in the top-right corner, and in the menu click
+ "Admin".
+3. You will see the Admin panel, with a table of projects that will
+ likely be empty. Click the "Add New Project" button.
+4. Fill the project creation form as follows:
+ * **Name**: Pontoon Test
+ * **Slug** (auto-filled): pontoon-test
+ * **Locales**: select Slovenian (sl), then add any locales you want
+ * **Repositories -> URL**:
+5. Leave the rest as it is, then scroll to the bottom of the page, and
+ click the "Save Project" button.
+6. Once the project is saved, scroll to the bottom of the page again,
+ and click the "Sync" button. This will pull the data from the
+ repository, and create entries for each of the locales you have
+ enabled.
+7. And that's it! You should now have a project enabled for some
+ locales.
+
+## 4. Verify your setup
+
+Setting up a project means more than installing it: it also means
+making sure that the tool runs and that tests pass.
+
+Once you have successfully installed and populated Pontoon on your
+computer, you will need to make a few verifications. First and foremost,
+make sure the site works correctly, and the data you created previously
+shows up. Make sure you can log in, that you can send some translations,
+that projects appear on the dashboards, etc.
+
+Second, you will want to run the tests and make sure they pass. We have
+a few test suites for Pontoon, some for the front-end, others for the
+back-end, as well as a few code-quality tests. To run all of the tests
+(same as what will happen when you open a pull request in GitHub), use
+the command `make test`.
+
+When you have successfully verified that your setup works correctly, you
+can safely move to the next part.
+
+## 5. Choose an issue to work on
+
+You are now ready to make a contribution! Open source projects usually
+have a list of mentored issues that are appropriate to work on first,
+and on which mentors will be available to help you.
+
+Work that needs to be done on Pontoon is tracked in
+[GitHub](https://github.com/mozilla/pontoon/issues), where we maintain a
+list of what we deem [good first
+issues](https://github.com/mozilla/pontoon/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22).
+
+Look through that list for unassigned issues, choose one that is
+appealing to you and seems appropriate for your skill set, then comment
+on that issue asking to be assigned to it. Feel free to start working on
+it right away — even if you end up not being assigned for some reason,
+it will still be a good experience for you.
+
+## 6. Read the contributing rules
+
+Most projects have strict contributing rules, and your contributions
+risk not being accepted if you don't respect them.
+
+To make developer's lives easier, we enforce a few contribution rules
+around Pontoon. They range from how to style your code to how to write
+commit messages. All these rules are written in our [Contributing Guidelines](contributing.md).
+Please read it before opening a pull request!
+
+There is more documentation around Pontoon, and it is often worth
+reading it, if only to understand better how the tool works and how and
+where to make your contributions. Here are a few links to important
+documentation resources:
+
+- If you want to work on the front-end, it is important that you read
+ the [Front-End Documentation](https://github.com/mozilla/pontoon/tree/HEAD/translate).
+- Most of the documentation around installing and developing can be
+ found in the [Developer Guide](index.md).
+- For documentation about using Pontoon to localize, see the [Localizer Guide](../localizer/index.md).
+- For documentation about managing projects, locales and users, see the [Admin Guide](../admin/index.md).
+
+## 7. Communicate with us
+
+Open source projects are usually built around a community of people.
+Communicating with that community is an important part of contributing
+to such projects.
+
+There are two main places where we communicate about Pontoon's
+development. The first one is
+[chat.mozilla.org](https://chat.mozilla.org/), used for real-time chat,
+quick questions, side-track conversations, etc. Find us in the
+[#pontoon
+channel](https://chat.mozilla.org/#/room/#pontoon:mozilla.org).
+
+The second is [GitHub
+Discussions](https://github.com/mozilla/pontoon/discussions), a forum
+platform that we use for more long-term conversations.
+
+These are both places that we strongly encourage you to join, and they
+are where you should introduce yourself, ask questions, show your work,
+etc.
+
+Pontoon's core developer team is currently composed of Matjaž and
+Eemeli. We also regularly receive invaluable help from community
+members.
+
+| | Name | ROLE | chat.mozilla.org | github |
+|---------------------------------------------------------------------|--------|------------------------|------------------|------------------------------------------|
+|  | Matjaž | Pontoon Core Developer | mathjazz | [mathjazz](https://github.com/mathjazz/) |
+|  | Eemeli | Pontoon Core Developer | eemeli | [eemeli](https://github.com/eemeli/) |
diff --git a/documentation/docs/dev/index.md b/documentation/docs/dev/index.md
new file mode 100644
index 0000000000..23e14a3a9a
--- /dev/null
+++ b/documentation/docs/dev/index.md
@@ -0,0 +1,38 @@
+---
+hide:
+ - toc
+---
+
+# Developer Guide
+
+This guide covers everything you need to know to contribute to, deploy and maintain Pontoon.
+
+## Sections
+
+
+
+- :material-rocket-launch: **[First Contribution](first-contribution.md)**
+
+ Get started with contributing to Pontoon, including setting up your environment and submitting your first patch.
+
+- :material-tools: **[Developer Setup](developer-setup.md)**
+
+ How to set up Pontoon for local development.
+
+- :material-code-braces: **[Contributing](contributing.md)**
+
+ Guidelines and best practices for contributing code to Pontoon.
+
+- :material-source-branch: **[Feature Development Process](feature-development-process.md)**
+
+ Overview of how new features are designed, developed, and reviewed.
+
+- :material-cloud-upload: **[Deployment](deployment.md)**
+
+ Instructions for deploying Pontoon instances.
+
+- :material-cog: **[Maintenance](maintenance.md)**
+
+ Routine maintenance tasks and responsibilities.
+
+
diff --git a/documentation/docs/dev/maintenance.md b/documentation/docs/dev/maintenance.md
new file mode 100644
index 0000000000..5bb06838f8
--- /dev/null
+++ b/documentation/docs/dev/maintenance.md
@@ -0,0 +1,11 @@
+# Maintenance
+
+The following describes tricks and tools useful for debugging and maintaining a production instance of Pontoon.
+
+## Mitigating DDoS attacks
+
+In a [DDoS attack](https://en.wikipedia.org/wiki/Denial-of-service_attack), the incoming traffic flooding the victim originates from many different sources. This stops everyone else from accessing the website as there is too much traffic flowing to it.
+
+One way to mitigate DDoS attacks is to enable traffic throttling. Set the `THROTTLE_ENABLED` environment variable to `True` and configure other `THROTTLE*` variables to limit the number of requests per period from a single IP address.
+
+A more involved but also more controlled approach is to identify the IP addresses of the attackers (see the handy [IP detection script](https://github.com/mozilla-l10n/pontoon-scripts/blob/main/dev/check_ips_heroku_log.py) to help with that) and block them. Find the attacking IP addresses in the Log Management Add-On (Papertrail) and add them to the `BLOCKED_IPS` environment variable.
diff --git a/documentation/docs/index.md b/documentation/docs/index.md
new file mode 100644
index 0000000000..e32e74619d
--- /dev/null
+++ b/documentation/docs/index.md
@@ -0,0 +1,63 @@
+---
+hide:
+ - toc
+---
+
+# Welcome to Pontoon Documentation
+
+**Pontoon** is Mozilla's translation management system (TMS) — a web-based platform that enables the Mozilla localization community to translate, review, and manage strings for Mozilla's products and websites.
+
+Pontoon specializes in community-driven open source localization, pulling strings directly from version control repositories (Git and Mercurial) and writing translations back automatically. It supports a wide range of localization file formats including Fluent, Gettext PO, XLIFF, .properties, DTD, and more.
+
+!!! info "Scope of this documentation"
+ While most of this documentation applies to any Pontoon deployment, the Mozilla instance is used as the primary example. Some sections — particularly in the Admin Guide — are specific to Mozilla's deployment.
+
+---
+
+## Who is this documentation for?
+
+
+
+- :material-translate: **Localizers**
+
+ ---
+
+ You're a contributor who translates and reviews strings in Pontoon.
+
+ [:octicons-arrow-right-24: Localizer Guide](localizer/index.md)
+
+- :material-cog: **Admins & Project Managers**
+
+ ---
+
+ You manage Pontoon's projects, locales, users, and configuration.
+
+ [:octicons-arrow-right-24: Admin Guide](admin/index.md)
+
+- :material-code-braces: **Developers**
+
+ ---
+
+ You contribute to Pontoon's codebase or deploy your own instance.
+
+ [:octicons-arrow-right-24: Developer Guide](dev/index.md)
+
+
+
+---
+
+## Quick links
+
+| I want to… | Go to |
+|---|---|
+| Start translating a project | [How to Translate](localizer/translate.md) |
+| Add a new project | [Adding a New Project](admin/adding-new-project.md) |
+| Add a new locale | [Adding a New Locale](admin/adding-new-locale.md) |
+| Set up Pontoon locally for development | [Developer Setup](dev/developer-setup.md) |
+| Deploy Pontoon to production | [Deployment](dev/deployment.md) |
+
+---
+
+## About Pontoon
+
+Pontoon is developed and maintained by Mozilla and is available as open source software at [github.com/mozilla/pontoon](https://github.com/mozilla/pontoon). The Mozilla instance is hosted at [pontoon.mozilla.org](https://pontoon.mozilla.org).
diff --git a/documentation/docs/localizer/glossary.md b/documentation/docs/localizer/glossary.md
new file mode 100644
index 0000000000..befd32e036
--- /dev/null
+++ b/documentation/docs/localizer/glossary.md
@@ -0,0 +1,93 @@
+# Glossary
+
+Explanation of common terms and concepts used across documentation.
+
+## Comment
+
+Comments can be used, for example, to discuss possible translations with other team members or request more information from project managers.
+
+Pontoon supports two types of user comments:
+
+* *Source string comments* are associated with the source string and displayed in the `COMMENTS` tab in the right column.
+* *Translation comments* are associated with a specific translation and displayed under the editor in the [translation list](translation-workspace.md#translation-list).
+
+Comment authors can edit or delete their own comments. Project managers can also delete any comment for moderation purposes.
+
+User comments should not be confused with *Resource comments*, which developers can add directly to the resource file. This type of comment is displayed in the editing area, along with other information like the [resource path and context](#resource).
+
+## Fuzzy
+
+`fuzzy` is an internal state available only if the source file is a [gettext](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html) (.po) file. A string can be marked as such in a few cases:
+
+* The reference text changed after the string was already translated.
+* The string has been manually marked by translators because it needs review.
+* New strings were merged in the localized files, enabling the option to match existing translations (also called “fuzzy matching”).
+
+In all these cases a translation exists in the file, but is marked as fuzzy (equivalent to “need review”) and not used by the website or application. For more information, read the documentation about [Fuzzy Entries](https://www.gnu.org/software/gettext/manual/html_node/Fuzzy-Entries.html#Fuzzy-Entries) in gettext.
+
+## Locale
+
+A locale is the combination of a language and a region, represented in Pontoon by a locale code. For example, American English is referred to as `en-US`, where `en` stands for the language (English), and `US` for the region (United States). In some cases, the region is omitted, because the language is mostly spoken in one region.
+
+In Pontoon, each locale maps to a team.
+
+## Machine Translation
+
+Machine Translation (MT) is the translation of text from one language to another, performed by software without human involvement. There are different types of machine translation solutions (or "engines"), but all modern systems are based on a neural network approach (vs statistical or rule-based).
+
+In Pontoon, machine translation is used as part of the [pretranslation](#pretranslation) feature, powered by [Google AutoML Translation](https://cloud.google.com/translate/automl/docs) with custom models trained on existing translation memories.
+
+## Permission
+
+Users in Pontoon can have different permissions depending on their role:
+
+* Translators can either submit approved translations directly or review suggestions from other users. Unlike in some other Translation Management Systems, this is a single permission in Pontoon, and it’s referred to as *Translator permission*.
+* Team managers have translator permissions, but can also change permissions assigned to other users (i.e., ”promote” or ”demote” them).
+
+## Pretranslation
+
+Pretranslation is a feature in Pontoon that relies on machine translation ([Google AutoML Translation](https://cloud.google.com/translate/automl/docs)) and [translation memory](#translation-memory) to automatically translate strings and save them in localized files.
+
+If pretranslation is enabled for a combination of a locale and a project, when a new string is added in Pontoon:
+
+* It will be translated (pretranslated) using a 100% match from translation memory or, should that not be available, using the Google AutoML Translation engine with a custom model.
+* The string will be stored in Pontoon with the *pretranslated* status.
+* For projects using [version control systems](#version-control-system), the translation will be stored in localized files outside of Pontoon.
+
+## Resource
+
+Resources are localization files within a repository (see [version control system](#version-control-system)) used to store source content and translations. They can be in different file formats but generally follow the same key-value structure, where the key (displayed as `Context` in the Source string panel) is a unique identifier and the value is a text snippet that needs to be translated.
+
+## Terminology
+
+Terminology — sometimes also referred to as a *Glossary* — is a list of terms and their definitions. Pontoon will highlight any terms in the source string and show their definitions as well as translations into the target language.
+
+`TBX`, or *TermBase eXchange*, is a standard file format used in the translation industry to represent and exchange terminological information. Pontoon Terminology can be downloaded in the `TBX` format.
+
+## Translation
+
+A translation is any submission of the target content. There are several types of translations:
+
+* *Approved translations*: translations submitted directly or approved by users with translator permissions.
+* *Suggestions*: translations that have not been reviewed yet (pending).
+* *Pretranslations*: translations that have been authored by the pretranslation feature.
+
+## Translation memory
+
+Translation memory is a list of all approved translations for any string. It can be leveraged to provide suggestions when translating new content.
+
+`TMX`, or *Translation Memory eXchange*, is a standard file format used in the translation industry to represent and exchange translation memories. Pontoon Translation memory can be downloaded in the `TMX` format.
+
+## Translation mode
+
+Depending on their settings and permissions, users will be able to submit translations directly (*Translation Mode*), or only submit suggestions (*Suggestion Mode*).
+
+Contributors — users without translator permissions — can only access *Suggestion Mode*, while translators and team managers can manually switch between the modes.
+
+## Version Control System
+
+Most projects store source content and translations outside of Pontoon, in repositories that use [version control systems (VCS)](https://en.wikipedia.org/wiki/Version_control). The most popular are git and Mercurial (hg).
+
+Pontoon periodically (usually every 10 minutes) imports source content and translations from these repositories and writes translations back. This process is referred to as *Sync*.
+
+Pontoon also supports the so-called `DB projects`, where source content and translations are stored in Pontoon’s internal database (DB).
diff --git a/documentation/docs/localizer/index.md b/documentation/docs/localizer/index.md
new file mode 100644
index 0000000000..e494dcaac3
--- /dev/null
+++ b/documentation/docs/localizer/index.md
@@ -0,0 +1,45 @@
+---
+hide:
+ - toc
+---
+
+# Localizer Guide
+
+This guide covers everything you need to know to translate and review strings in Pontoon, from day-to-day translation work to managing your account and notifications.
+
+!!! note
+ The screenshots in this documentation use the dark theme, but a light theme is also available in your [profile settings](users.md).
+
+## Sections
+
+
+
+- :material-pencil: **[How to Translate](translate.md)**
+
+ Step-by-step guide to submitting translations and suggestions, reviewing other contributors' work, and an example team workflow.
+
+- :material-view-dashboard: **[Translation Workspace](translation-workspace.md)**
+
+ A detailed tour of the translation editor: the sidebar, string filters, machinery tab, AI refinement, comments, and keyboard shortcuts.
+
+- :material-folder-multiple: **[Team & Project Pages](teams-projects.md)**
+
+ How to navigate team dashboards, project pages, and localization pages; how to request new projects or locales.
+
+- :material-account-cog: **[User Accounts & Settings](users.md)**
+
+ Account setup, roles and permissions, profile visibility settings, and personal preferences.
+
+- :material-bell: **[Notifications](notifications.md)**
+
+ How Pontoon notifies you of new strings, reviews, mentions, and project updates.
+
+- :material-account: **[Profile Page](profile.md)**
+
+ What's on your public profile and how to customize it.
+
+- :material-book-open-variant: **[Glossary](glossary.md)**
+
+ Definitions of key terms used throughout Pontoon and this documentation.
+
+
diff --git a/documentation/docs/localizer/notifications.md b/documentation/docs/localizer/notifications.md
new file mode 100644
index 0000000000..d173f969bb
--- /dev/null
+++ b/documentation/docs/localizer/notifications.md
@@ -0,0 +1,75 @@
+# Notifications
+
+Tracking updates across several projects can quickly become challenging. Pontoon tries to support users across different roles by sending notifications, to make sure important updates don’t get lost. Administrators can also use notifications to send messages about specific projects.
+
+When the user receives a notification, the bell icon near the user avatar in the top right corner will show a badge with the number of unread notifications. Clicking the bell icon will display the latest notifications in a dropdown menu.
+
+
+
+Clicking `See all Notifications` at the bottom will take the user to the complete list of notifications. The same list can also be accessed by opening the `/notifications` URL directly (e.g. [pontoon.mozilla.org/notifications](https://pontoon.mozilla.org/notifications/)).
+
+## Receiving notifications via email
+
+Pontoon also offers the option to receive notifications via email, allowing users to stay informed about important events even when they're not actively using the platform. They can [choose to receive email notifications](users.md#user-settings) as a daily or weekly digest and customize their preferences by subscribing to specific notification types.
+
+## Receiving notifications in the browser
+
+Pontoon notifications can be delivered directly to your browser through the Pontoon Add-on, which is compatible with both [Firefox](https://addons.mozilla.org/firefox/addon/pontoon-tools/) and [Chrome](https://chrome.google.com/webstore/detail/pontoon-add-on/gnbfbnpjncpghhjmmhklfhcglbopagbb).
+
+## Disabling notifications
+
+Pontoon includes several types of notifications and most of them can be [manually disabled](users.md#notification-subscriptions) by users if they don’t find them useful.
+
+## Notification types
+
+### New strings
+
+This notification informs users when new strings are added to a project. The notification is sent to all users who contributed translations to that project, as soon as new strings are available.
+
+### Project target dates
+
+This notification informs users when a project is incomplete and it’s approaching the target date. The notification is sent to all users who contributed translations to that project, the first time 7 days before the target date, then again 2 days before.
+
+### Comments
+
+Pontoon distinguishes between two types of comments:
+
+* **Translation comments** are associated with a specific translation. These comments are displayed under the translation itself.
+* **Source string comments** are associated with the source string. These comments are displayed in the `COMMENTS` tab in the right column.
+
+For either type of comment, a notification is sent as soon as a comment is added.
+
+For translation comments, the recipients are:
+
+* Users with the ability to review translations for the string.
+* Authors of other translation comments associated with the same translation.
+* Translation author.
+* Translation reviewer.
+
+For source strings comments, the recipients are:
+
+* Users with the ability to review translations for the string.
+* Authors of translation comments.
+* Authors of source string comments.
+* Translation authors.
+* Translation reviewers.
+
+### New suggestions ready for review
+
+This notification is sent once a week to inform reviewers about new suggestions needing a review. It includes information about suggestions that were submitted, unapproved or unrejected over the last 7 days. Recipients include users with permissions to review these suggestions — translator and team managers — as well as the authors of previous translations or comments in the same string.
+
+### Review actions on own suggestions
+
+This notification is sent once a day to authors of suggestions, to inform them that their work has been reviewed.
+
+### New team contributors
+
+This notification is sent to team managers, as soon as a new user makes the first contribution to their team.
+
+### Badge awarded
+
+This notification is sent to a user upon being awarded with a [badge or new badge level](profile.md#achievement-badges) from reviewing and submitting translations, or promoting users.
+
+### Manual notifications
+
+Administrators can send manual notifications to a project, including all locales or a subset of them. Unlike other types of notifications, this can’t be disabled.
diff --git a/documentation/docs/localizer/profile.md b/documentation/docs/localizer/profile.md
new file mode 100644
index 0000000000..239e8e3566
--- /dev/null
+++ b/documentation/docs/localizer/profile.md
@@ -0,0 +1,51 @@
+# Profile Page
+
+The goal of the profile page in Pontoon is to provide a tool to showcase contributions, display useful contact information about the user, and help team managers to organize and grow their communities. A user’s personal profile page can be reached by clicking the avatar icon in the top right corner, and then clicking the profile picture in the dropdown menu, or by using the `/profile` URL (e.g. [pontoon.mozilla.org/profile](https://pontoon.mozilla.org/profile)). Users can also view others’ personal profiles by clicking a user’s profile picture wherever it appears, such as in the list of contributors for a team or project.
+
+The left column includes information about the user:
+
+* Profile picture and name.
+* Contact details.
+* Achievement badges.
+* Information on last known activity (when the user has submitted or reviewed a translation), last login in Pontoon, and the account’s creation date.
+* Roles in Pontoon (a user can have multiple roles across different locales).
+
+Users can customize their information and the visibility of specific fields in the [settings page](users.md#user-settings) (reachable using the `CHANGE SETTINGS` button).
+
+## Achievement badges
+
+Achievement badges awarded to a user are displayed beneath their contact information. The available badge types, from left to right in the image below, include:
+
+* **Translation Champion**, awarded for submitting translations.
+* **Review Master**, awarded for reviewing translations.
+* **Community Builder**, awarded for promoting users to higher roles.
+
+
+
+Each badge has multiple levels. If a user holds a badge at level two or higher, the level is shown at the bottom left of the badge icon.
+
+Whenever they earn a new badge or level up an existing badge, users will be notified with a pop-up and a notification.
+
+## Activity graphs
+
+In the top central section there are two graphs:
+
+* **Approval rate** shows the ratio between the number of translations approved and the total number of translations reviewed, excluding self-approved translations.
+* **Self-approval rate** is only visible for users with translator rights, and shows the ratio between the number of translations submitted directly — or self-approved after submitting them as suggestions — and the total number of translations approved.
+
+
+
+If both graphs are available, it’s possible to switch between them using the selector at the bottom (highlighted in red in the image above)
+
+Right below these graphs, there is a section showing a graphical representation of the user’s activity in the last year. Each square represents a day, while each row represents a day of the week. The brighter the color, the higher the number of contributions on that day.
+
+
+
+By default, the chart will show data for **all contributions** over the last year, but it’s also possible to limit the chart to:
+
+* Submissions.
+* Reviews performed.
+* Reviews received.
+* Submissions and reviews.
+
+The activity log below this chart will display the user’s activity in more detail for the last month. Clicking on a specific square (day) in the chart will only show the activity for that day. Each line item in the activity log is a link that allows to jump to those specific strings in the translation editor.
diff --git a/documentation/docs/localizer/search.md b/documentation/docs/localizer/search.md
new file mode 100644
index 0000000000..7c159c78f3
--- /dev/null
+++ b/documentation/docs/localizer/search.md
@@ -0,0 +1,106 @@
+# Translation Search & Entity Translations
+The Translation Search page, accessible using the `/search` URL (e.g. [pontoon.mozilla.org/search](https://pontoon.mozilla.org/search/)), allows users to search for translations across all projects and locales in Pontoon. From the search results, users can access the [Entity Translation page](#entity-translations-page), which displays all available translations for a specific source string across all locales.
+
+## Translation Search page
+
+The Translation Search page provides a powerful interface for searching translations. It can be reached by using the `/search` URL (e.g. [pontoon.mozilla.org/search](https://pontoon.mozilla.org/search/)).
+
+
+
+### Search interface
+
+The main search interface consists of:
+
+* **Search field**: A text input where users type their search query. Press Enter or click the `SEARCH` button to execute the search.
+* **Project selector**: A dropdown menu to filter results by a specific project, or search across `All Projects` (default).
+* **Locale selector**: A dropdown menu to select the target locale for translations. Defaults to the user’s preferred locale or `en-GB`.
+* **Search options**: A group of checkboxes to further filter based on user preferences.
+
+Both the project and locale selectors include a search field to quickly filter through available options.
+
+
+
+#### Search options
+
+Three checkbox options allow users to refine their search:
+
+* **Search in string identifiers**: When enabled, the search also matches against string keys/identifiers (e.g., `community-exp`), not just the source and translation strings. This option is only relevant for non-gettext formats.
+* **Case sensitive**: When enabled, the search becomes case-sensitive. For example, searching for `Firefox` will not match `firefox`.
+* **Entire words**: When enabled, the search matches only complete words. For example, searching for `fire` will not match `Firefox`.
+
+The default state of these options can be configured in the [user settings page](users.md#default-search-options).
+
+### Search results
+
+Search results are displayed in a two-column layout:
+
+* **Source column**: Shows the original source string.
+* **Translation column**: Shows the translation in the selected locale.
+
+Matching text is highlighted in both columns to make it easy to identify where the search query was found.
+
+
+
+Each search result entry includes:
+
+* **Project name**: A link to the project page.
+* **String identifier**: The key or identifier for the string (displayed for non-gettext formats).
+* **Action buttons**:
+ * **All Locales**: Opens the [Entity Translation page](#entity-translations-page) to view translations in all available locales.
+ * **Edit**: Opens the translation string in the [translate workspace](translation-workspace.md) for direct editing.
+ * **Copy**: Copies the translation string to the clipboard.
+
+If no translations are available, a message `No results found.` is displayed.
+
+#### Infinite scroll
+
+Search results are loaded progressively as the user scrolls down the page. When the user approaches the bottom of the current results, additional results are automatically fetched and appended. This allows for efficient browsing of large result sets.
+
+### URL parameters
+
+The search state is preserved in the URL, making it easy to share or bookmark specific searches. The following URL parameters are supported:
+
+* `search`: The search query text.
+* `locale`: The locale code (e.g., `de`, `fr`, `ar`).
+* `project`: The project slug to filter by.
+* `search_identifiers`: Set to `true` to enable searching in string identifiers.
+* `search_match_case`: Set to `true` for case-sensitive search.
+* `search_match_whole_word`: Set to `true` to match entire words only.
+* `pages`: The number of result pages that have been loaded (used to restore scroll position).
+
+Example URL: `/search?search=Firefox&locale=de&project=firefox&search_match_case=true`
+
+## Entity Translations page
+
+The Entity Translations page displays all translations for a specific string across all available locales. It can be accessed in two ways:
+
+1. By clicking the `All Locales` button on a search result in the Translation Search page.
+2. By navigating directly to `/entities/{entity_id}/` (e.g. [pontoon.mozilla.org/entities/123](https://pontoon.mozilla.org/entities/123/)).
+An alternate URL format is also available: `/entities/{project_slug}/{resource_path}/{entity_key}/` (e.g. [pontoon.mozilla.org/entities/firefox/browser/branding/official/brand.ftl/-brand-shorter-name](https://pontoon.mozilla.org/entities/firefox/browser/branding/official/brand.ftl/-brand-shorter-name/)).
+
+
+
+### Source string section
+
+At the top of the page, the source string is displayed in a highlighted container, including:
+
+* **Source string**: The source text.
+* **Project name**: A link to the project page.
+* **String identifier**: The key or identifier for the string (displayed for non-gettext formats).
+* **Copy button**: Copies the source string to the clipboard.
+
+
+
+### Translation list
+
+Below the source string, a list shows all translations across available locales:
+
+* **Translation string**: The translated text.
+* **Locale information**: The locale name and code, which links to the team page.
+* **Action buttons**:
+ * **Edit**: Opens the string in the [translation workspace](translation-workspace.md) for editing in that specific locale.
+ * **Copy**: Copies the translation text to the clipboard.
+
+If no translations are available, a message `No translations found.` is displayed.
+
+
diff --git a/documentation/docs/localizer/teams-projects.md b/documentation/docs/localizer/teams-projects.md
new file mode 100644
index 0000000000..a4064d6331
--- /dev/null
+++ b/documentation/docs/localizer/teams-projects.md
@@ -0,0 +1,165 @@
+# Team & Project Pages
+The Teams page, accessible using the `/teams` URL (e.g. [pontoon.mozilla.org/teams](https://pontoon.mozilla.org/teams/)), lists all locales that are enabled in Pontoon. From here it’s possible to access a specific [Team page](#team-page), which contains a list of all projects enabled for the requested locale. Selecting a project from the Team page leads to the so-called the [Localization page](#localization-page).
+
+From each locale’s Team page it’s also possible to [Request a project](#requesting-a-project) or [Request pretranslation](#requesting-pretranslation). Note that this is a request to add the locale to a project already available in Pontoon, it can’t be used for requesting a brand new project.
+
+The Projects page, accessible using the `/projects` URL (e.g. [pontoon.mozilla.org/projects](https://pontoon.mozilla.org/projects/)), lists all projects that are available in Pontoon. From here it’s possible to access a [Project page](#project-page), which shows all locales that are enabled for the requested project. Selecting a locale in the Project page leads to the [Localization page](#localization-page).
+
+There is also a special Localization page that allows access to all resources for all projects enabled for a specific locale: `/locale/all-projects/all-resources`.
+
+The following diagram shows how these pages are organized and connected to each other:
+
+
+
+## Teams
+
+### Teams page
+
+The Teams page lists all locales that are enabled in Pontoon. It can be reached by clicking `Teams` in the page header (not displayed when translating a project) or by using the `/teams` URL (e.g. [pontoon.mozilla.org/teams](https://pontoon.mozilla.org/teams/)). Clicking on a specific locale will open the locale’s [Team page](#team-page).
+
+### Team page
+
+Access a specific team’s page by selecting it from the Teams page or by appending a locale code to the end of the Pontoon base URL with `/{LOCALE}` (e.g [pontoon.mozilla.org/it](https://pontoon.mozilla.org/it) for Italian).
+
+The page header contains linguistic information about the current locale (plural form, writing direction, etc.), plus an indication of the overall status of completion and statistics. The statistics displayed in the rightmost column are active links to access the [translation workspace](translation-workspace.md) for all projects. For example, select `ALL STRINGS` to show all the strings for all projects enabled for a specific locale in Pontoon, or select `MISSING` to filter for all strings missing translations.
+
+
+
+Underneath the header, the following tabs are available to navigate between various Team page panels:
+
+* **Projects**: a list of all projects enabled in Pontoon for this locale.
+* **Contributors**: a list of active contributors with their statistics, filterable by time (all time, last 12/6/3/1 months).
+* [**Insights**](#insights-graphs): data and trends on contributor and localization activity.
+* **Bugs**: a list of open bugs for the locale, retrieved from [Bugzilla](https://bugzilla.mozilla.org/) (available in Mozilla's deployment).
+* **Info**: information about the team. Team managers can edit this by clicking on the `EDIT` button.
+* **Permissions**: [permissions management panel](users.md#managing-permissions) (available to [Team Managers](users.md#user-roles)).
+* **TM**: [translation memory management](#translation-memory-management) panel (available to [Translators](users.md#user-roles) and [Team Managers](users.md#user-roles)).
+
+By default, the Projects tab opens, showing a list of all projects enabled for the locale. Clicking on one of these projects leads to the [Localization page](#localization-page). Column headers can be used to sort the list of projects. For example, clicking on `Priority` will sort projects by their priority.
+
+Hovering a project in the Projects list will replace the progress bar with a set of detailed statistics (untranslated strings, missing strings, etc.). Note that all these numbers are links, use them to open the project with a filter already enabled, for example to display only missing strings. Clicking `ALL` accesses All Resources (i.e. all strings in all files) for this project.
+
+The rightmost column in the table will display a blue lightbulb icon if there are unreviewed translations. Note: clicking the lightbulb icon in the table header can be used to sort projects based on the number of unreviewed translations.
+
+
+
+### Requesting a project
+
+It’s possible to request a project from a Team page. Note that this is a request to add the locale to a project already available in Pontoon, it can’t be used for requesting a brand new project.
+
+
+
+The button is hidden if all available projects are already enabled for the locale.
+
+Click on `REQUEST MORE PROJECTS`, select the projects to add and then click `REQUEST NEW PROJECT` (at least one project needs to be selected for the button to be displayed).
+
+An email will be sent to Pontoon’s administrators, and the Project manager in charge of the project will act on the request. Please note that:
+
+* Some projects have a closed list of supported locales, meaning that these projects can’t be requested on Pontoon.
+* Some projects can be requested but may not be enabled for practical restrictions related to the project itself (e.g. lack of support for the locale in iOS).
+
+### Requesting pretranslation
+
+For [locales supported by Google AutoML Translation](https://cloud.google.com/translate/automl/docs/languages), it’s possible to request to enable [pretranslation](glossary.md#pretranslation) for specific projects from a Team page.
+
+
+
+The button is only displayed to translators and team managers for the locale.
+
+Click on `REQUEST PRETRANSLATION`, select the projects to add and then click `REQUEST PRETRANSLATION` (at least one project needs to be selected for the button to be displayed).
+
+An email will be sent to Pontoon’s administrators, and they will act on the request. Please note that:
+
+* If a locale doesn’t have pretranslation enabled for any projects yet, it’s necessary to set up and train a new custom model, and this operation requires several hours.
+* For `pontoon.mozilla.org`, each request will be evaluated against specific [opt-in guidelines](https://mozilla-l10n.github.io/documentation/tools/pontoon/managing_pretranslation.html#opt-in-guidelines-to-enable-new-locales).
+
+### Translation memory management
+
+The TM ([translation memory](glossary.md#translation-memory)) tab lists all TM entries for the team. A source string and translation are provided for each entry, which upon clicking leads to the [translation workspace](translation-workspace.md) for the corresponding strings. Entries are only shown once for each unique combination of source string and translation. TM entries can be searched by source string or translation using the `Search` field.
+
+
+
+The following actions are available:
+
+* **Edit**: after clicking the `Edit` button in the Actions column, the translation of the TM entry transforms into a textarea element and becomes editable. Next to it, `Save` and `Cancel` buttons appear. Clicking `Save` saves any changes to all corresponding TM entries and clicking `Cancel` cancels the editing action.
+* **Delete**: after clicking the `Delete` button in the Actions column, the button changes into the `Delete N TM entries?` confirmation button (with N representing the number of corresponding TM entries). Clicking that button deletes all corresponding TM entries and clicking `Cancel` cancels the editing action.
+* **Upload .TMX**: after clicking the `Upload .TMX` button above the TM entry list, an Open file dialog pops up. The user then selects the [TMX file](glossary.md#translation-memory) to upload, the TM entries from the file start to import into the team's TM, and eventually a success or error message appears.
+
+## Projects
+
+### Projects page
+
+The Projects page lists all projects that are available in Pontoon. It can be reached by clicking `Projects` in the page header (not displayed when translating a project) or by using the `/projects` URL (e.g. [pontoon.mozilla.org/projects](https://pontoon.mozilla.org/projects/)). Clicking on a specific project will open the [Project page](#project-page).
+
+### Project page
+
+Access a project’s page by selecting it from the Projects page (e.g. [pontoon.mozilla.org/projects](https://pontoon.mozilla.org/projects/)).
+
+The page header contains useful information about the current project:
+
+* **Priority**: priority from 5 stars (highest) to 1 star (lowest).
+* **Target date**: set only for some projects, it indicates when the translation is due.
+* **Repository**: link to the repository storing translations for this project.
+* **Resources**: links to useful external resources (e.g. testing instructions, screenshots, etc.). Project managers can set up custom links for each project.
+* **Project manager**: point of contact for this project.
+
+It also includes an indication of the overall status of completion and statistics across all enabled languages.
+
+
+
+Underneath the header, the following tabs are available to navigate between various Team page panels:
+
+* **Teams**: a list of all locales enabled in Pontoon for this project.
+* **Tags**: a list of tags defined for this project. This tab will be visible only in projects where tags are enabled. For more information about tags, see [this page](translation-workspace.md#tags).
+* **Contributors**: a list of active contributors with their statistics, filterable by time (all time, last 12/6/3/1 months).
+* [**Insights**](#insights-graphs): data and trends on contributor and localization activity.
+* **Info**: information about the project.
+
+By default, the Teams tab opens, showing a list of all locales enabled for the project. Clicking on one of these locales leads to the [Localization page](#localization-page).
+
+### Requesting a locale
+
+It’s possible to request an additional locale for some projects from its Project page.
+
+
+
+Click on `REQUEST NEW LANGUAGE`, select the locale to add and then click `REQUEST NEW LANGUAGE`.
+
+An email will be sent to Pontoon’s administrators, and the Project manager in charge of the project will act on the request. The same restrictions described in the [Requesting a project](#requesting-a-project) section apply here.
+
+## Localization page
+
+Access a project’s Localization page in two ways:
+
+* By selecting it from the [Team page](#team-page).
+* By selecting it from the [Project page](#project-page).
+
+The page header contains useful information about the current project (same as the [Project page](#project-page)).
+
+
+
+Underneath the header, the following tabs are available to navigate between various Team page panels:
+
+* **Resources**: files available in the project.
+* **Tags**: a list of tags defined for this project. This tab will be visible only in projects where tags are enabled. For more information about tags, see [this page](translation-workspace.md#tags).
+* **Contributors**: a list of active contributors with their statistics, filterable by time. Unlike the tab available in the Team page, this only includes contributions to localization of the project for the current locale.
+* [**Insights**](#insights-graphs): data and trends on contributor and localization activity.
+* **Project info**: same content as the Info tab in the Project page.
+* **Team info**: same content as the Info tab in the Team page.
+
+## Insights graphs
+
+The Insights tab, accessible from either the Project, Team, or Localization page, displays data and trends on contributor and localization activity in a graphical format.
+
+The following insights appear on all pages:
+
+* **Review activity**: shows the number of unreviewed suggestions as a trend line. The Team page also shows the number of peer-approved, self-approved, and rejected suggestions for each month as a bar graph to display the impact of the review process on the number of unreviewed suggestions. New suggestions (hidden by default) can also be shown by clicking `New suggestions` at the bottom of the graph. Hover over a data point to get the detailed number of strings and percentages for that month.
+* **Translation activity**: shows the translation completion percentage for the locale as a trend line. The Team page also shows the number of human translations and [machinery translations](translation-workspace.md#machinery) for each month as a bar graph to display the impact of the translation process on the number of completed translations. New source strings (hidden by default) can also be shown by clicking `New source strings` at the bottom of the graph. Hover over a data point to get the detailed number of strings and percentages for that month.
+
+The following insights only appear on Team pages:
+
+* **Active users**: shows the ratio of active versus total for each [user role](users.md#user-roles): managers (Team managers), reviewers (Team managers and Translators), and contributors, filterable by time period (last 12/6/3/1 months).
+* **Time to review suggestions**: shows the average age of [suggestions](glossary.md#translation) reviewed for a particular month, and the 12 month average. Hover over a data point in the graph to see the exact age in days for that month’s current and 12 month average.
+* **Age of unreviewed suggestions**: this can be accessed by clicking `Age of unreviewed` on the bottom of the Time to review suggestions graph. Shows the average age of unreviewed suggestions at a particular point in time. Hover over a data point in the graph to see the exact age in days for unreviewed suggestions for that month.
+
+Note: clicking on the `i` icon in the top right of each insight will provide detailed definitions for the data shown.
diff --git a/documentation/docs/localizer/translate.md b/documentation/docs/localizer/translate.md
new file mode 100644
index 0000000000..e6c783deae
--- /dev/null
+++ b/documentation/docs/localizer/translate.md
@@ -0,0 +1,163 @@
+# How to Translate
+
+This document describes briefly how to translate and review strings in Pontoon and provides an [example of translation workflow within a team](#workflow-example). The documentation also includes a dedicated page about Pontoon’s [translation workspace](translation-workspace.md), including [translation tools](translation-workspace.md#translation-tools-and-comments).
+
+## Translating strings
+
+When a string is selected in the sidebar, users can input a translation using the editor available in the middle of the page. Note that, if the string already has a [translation](glossary.md#translation), the editor will be pre-populated with text that the user can modify.
+
+Depending on the current [translation mode](glossary.md#translation-mode), the UI will look slightly different.
+
+When the user is in *Suggestion Mode* — [manually selected](#manually-switch-to-suggestion-mode), or because the user doesn’t have permissions to submit translations directly — a blue `SUGGEST` button will be displayed in the lower-right side of the editing space.
+
+
+
+To suggest a translation, the user can input the text in the editor and click `SUGGEST`. The suggestion will then be displayed below the editing space and in the sidebar where, in the case of multiple suggestions, only the most recent one will be displayed.
+
+Note that a suggestion exists only in the Pontoon database, and it’s not added to the [translation memory](glossary.md#translation-memory). For projects using [version control systems](glossary.md#version-control-system), the translation is not stored in localized files outside of Pontoon.
+
+When the user is in *Translation Mode*, a green `SAVE` button will be displayed instead of `SUGGEST`. When saving a translation:
+
+* The translation will be displayed directly below the editing space and in the sidebar.
+* The translation will be stored in the version control system (where applicable).
+* All pending suggestions or [pretranslations](glossary.md#pretranslation) will be rejected.
+
+### Manually switch to suggestion mode
+
+Even if the user has permissions to add translations directly, submitting suggestions to be reviewed by another person helps ensure quality. To manually switch to *Suggestion Mode*, click the settings icon in the lower-left side of the editing space and select `Make suggestions`. The `SUGGEST` button will be displayed in the lower-right side of the editing space, replacing the green `SAVE` button.
+
+
+
+To switch back to *Translation Mode*, click the settings icon again and turn off `Make suggestions`.
+
+## Reviewing strings
+
+To review a suggestion or pretranslation, [search](translation-workspace.md#search) for unreviewed or pretranslated strings in the sidebar.
+
+If the current translation is acceptable, either click on the `APPROVE` button in the lower-right side of the editing space, or click on the approve icon to the right of the text. This will transform the suggestion or pretranslation into an approved translation. In the case of suggestions, the approved translation will also be stored in the version control system (where applicable).
+
+
+
+If the current translation is **not** acceptable, it can be rejected by clicking the reject icon to the right of the suggestion. After rejecting a suggestion or pretranslation, it’s also possible to delete it completely by clicking the trashcan icon. In the case of pretranslations, the rejected text will be also removed from version control systems (where applicable).
+
+Alternatively, it’s possible to provide a different suggestion: turn on `Make suggestions`, edit the translation as appropriate, and click `SUGGEST`. This will add the translation as a new suggested string.
+
+## Quality checks
+
+When submitting a translation or suggestion, Pontoon performs automated quality checks. They are meant to help localizers identify issues with punctuation, capitalization, variables, etc. before translations are saved. Failures for these checks are stored in the database, and it’s possible to filter strings with issues from the search bar.
+
+There are two types of quality check failures: errors and warnings.
+
+### Errors
+
+Errors cover critical issues that would cause the string to be removed from products. For this reason, errors cannot be bypassed by localizers - the button to submit a translation is removed and the error needs to be fixed before the translation can be saved.
+
+Examples include exceeding the maximum string length, incorrect syntax, etc. Errors are denoted with a circled X with red background.
+
+
+
+### Warnings
+
+Warnings are displayed when potential issues are detected in the string, but it’s not certain that they will create problems in products (unlike errors). For that reason, warnings can be bypassed by localizers, allowing them to save a translation anyway.
+
+Examples include missing punctuation, differences in number of sentences and capitalization, etc. Warnings are denoted with a circled X with gray background.
+
+
+
+Certain types of checks reported by the Translate Toolkit library may result in many false positives. For this reason, they can be [completely disabled](users.md#editor-settings).
+
+## Performing batch actions on strings
+
+Mass actions can be performed on multiple strings at once by clicking on the square to the left of any string in the sidebar. When clicked, the square will show a checkmark and the editing space will show the mass action panel. Note that mass actions are only available to users with [translator permissions](users.md#user-roles).
+
+
+
+To select a range of strings, select the first one and hold `SHIFT`, then select the last one. To select all strings, click `SELECT ALL` on the top-right of the mass action panel. The number of selected strings will appear on the top-left, next to the Exit icon.
+
+To return back to the default editing space, click the Exit icon on the top-right of the mass action panel.
+
+In the `REVIEW TRANSLATIONS` section, the user can approve or reject suggestions for all selected strings. Upon clicking `APPROVE ALL` or `REJECT ALL SUGGESTIONS`, the label of the button will be replaced with the number of affected translations.
+Note that `APPROVE ALL` accepts the latest suggestion, but doesn’t reject other suggestions if available.
+
+In the `FIND & REPLACE IN TRANSLATIONS` section, the user can input the text to search for, and the text to replace it with. This is a basic find and replace feature that will work only on the selected strings.
+
+## Downloading and uploading translations
+
+Pontoon provides the ability to download and upload translations, including [terminology](glossary.md#terminology) and [translation memories](glossary.md#translation-memory). To access these features, click on the profile icon in the top-right corner of any page. Note that the user must be in the translation workspace for the download/upload options to be displayed in the dropdown menu.
+
+
+
+Anyone can download terminology (`.tbx`), translation memory (`.tmx`) and translations, while only users with translator permissions can upload translations. When downloading translations:
+
+* The resource currently selected is downloaded in its original format, it’s not converted in any way.
+* If the project contains multiple files, a ZIP of all files is downloaded. If the project contains more than 10 files, only the file currently translated will be downloaded.
+
+When uploading translations to Pontoon:
+
+* Translations different from the ones in Pontoon will be imported and attributed to the user uploading the file.
+* Translations matching the ones in Pontoon will be ignored.
+
+## Downloading .tbx and .tmx files via command line
+
+Terminology (`.tbx`) and translation memory (`.tmx`) files can grow big in size over time. To download files via command line it is advised to use `curl` command with the `--compressed` flag, to reduce download times and avoid request timeouts.
+
+Here’s an example command to download German (de) .tmx file across all projects from `pontoon.mozilla.org`:
+
+```
+curl -o de.all-projects.tmx --compressed https://pontoon.mozilla.org/translation-memory/de.all-projects.tmx
+```
+
+Note that Terminology files can be downloaded in the `TBX 2008 (v2)` format in addition to the default `TBX v3` format available via the profile menu.
+
+Here’s an example command to download German (de) .tbx file in the `TBX 2008 (v2)` format from `pontoon.mozilla.org`:
+
+```
+curl -o de.v2.tbx --compressed https://pontoon.mozilla.org/terminology/de.v2.tbx
+```
+
+## Workflow example
+
+This workflow utilizes the full power of Pontoon’s online translation features. It assumes that at least two translators are available for the project (*AB workflow*); however, this workflow can be completed by a single translator performing each phase (*AA workflow*), or by multiple translators in an *ABCn workflow* repeating Phase 3.
+
+### Phase 1: translation
+
+#### Translator A
+
+1. Log in to Pontoon.
+2. Browse to the [project](teams-projects.md).
+3. Using [filters](translation-workspace.md#search) select `Missing` to display only the strings currently missing a translation, marked as [fuzzy](glossary.md#fuzzy) or containing errors.
+4. Access personal settings by clicking on the gear icon below the editing field and turn on `Make suggestions`. Note that new contributors who have not yet been granted [Translator permissions](users.md#user-roles) will only have the ability to `Make suggestions`, which will be enabled by default.
+5. For each string, type a translation and save it with the blue `SUGGEST` button. The string will be stored and displayed under the editor. Each translation submitted shows the name of the author and when it was saved.
+ * If something is unclear or there is a question about the source string, use the [REQUEST CONTEXT or REPORT ISSUE](translation-workspace.md#source-string) feature to ask the [Project manager](users.md#user-roles).
+
+General notes:
+
+* Rely on Pontoon’s [translation tools](translation-workspace.md#translation-tools-and-comments) to ensure consistency and make the translation process faster.
+* When using Firefox, make sure to have a [dictionary](https://addons.mozilla.org/firefox/language-tools/) installed for the translation language, and that spell checking is enabled in the translation text area.
+
+### Phase 2: review suggestions
+
+#### Translator B
+
+1. Log in to Pontoon.
+2. Browse to the [project](teams-projects.md).
+3. In [filters](translation-workspace.md#search) select `Unreviewed`, to isolate the strings previously suggested by another translator.
+4. Review the suggested strings.
+ * If a suggestion is acceptable:
+ * Confirm it as an approved translation by clicking the green `SAVE` button or the checkmark icon near the string in the list below the editor (it turns green when hovered).
+ * If a suggestion is not acceptable:
+ * Switch to [Suggest mode](translate.md). Edit the translation in the editing space and click the blue `SUGGEST` button. The newly suggested version will **not** overwrite the translator’s work, but instead will appear at the top of the list under the editor.
+ * Use [translation comments](glossary.md#comment) to discuss a translation with the other translator. For example, discussing possible alternate translations or asking questions when something isn’t clear.
+
+### Phase 3: implementing QA
+
+#### Translator A
+
+1. In the project, select `Unreviewed` from the filter search. Then compare the initial entries with those of the reviewer for changes.
+2. Review the remaining strings:
+ * If in agreement, confirm the reviewer’s version by clicking the green `SAVE` button or the checkmark icon near the string in the list below the editor (it turns green when hovered).
+ * If suggesting an alternative, type it into the editor, then hit the blue `SUGGEST` button. Then resubmit it to the reviewer from Phase 2.
+ * Reject suggestions not considered suitable by clicking on the cross icon near the string (it turns red when hovered).
+ * If Translator A does not have the Translator or Team manager role, they will be unable to confirm or reject a suggestion. In that case, use [translation comments](glossary.md#comment) to discuss the translation with the reviewer.
+
+Repeat, switching translators, until a consensus is reached.
diff --git a/documentation/docs/localizer/translation-workspace.md b/documentation/docs/localizer/translation-workspace.md
new file mode 100644
index 0000000000..5a33027900
--- /dev/null
+++ b/documentation/docs/localizer/translation-workspace.md
@@ -0,0 +1,336 @@
+# Translation Workspace
+Pontoon’s translation workspace consists of the main toolbar and 3 columns:
+
+* The left column contains the string list for the current resource with a search field at the top.
+* The middle column contains the main editing space.
+* The right column contains terminology, source string comments, suggestions from translation memory, machine translation, and translations from other locales.
+
+
+
+## Main toolbar
+
+The main toolbar at the top of the page allows users to navigate to the dashboards or to change the current resource.
+
+
+
+Clicking the locale name will open the [Team page](teams-projects.md#team-page) for that locale, while clicking the project name will open the [Localization page](teams-projects.md#localization-page) for that project.
+
+Clicking on the current resource (or `All Resources`) will display a list of all resources available for that project. It’s possible to search for a resource, and click one to load only the entities included in it. Clicking `All Resources` at the bottom of the list will go back to display all resources, while `All Projects` will show entities for all projects under the selected locale.
+
+A progress chart showing the translation status of the current resource is located to the right of the resource name. A more detailed breakdown is displayed when clicking the chart.
+
+
+
+The notifications icon, represented by a bell, is located on the right side of the main toolbar. By clicking the bell icon, users can view a list of the latest [notifications](notifications.md) they received.
+
+The profile menu is located at the far right of the main toolbar. Clicking the profile image will reveal a dropdown menu where users can perform several actions, like navigate to their [profile page](profile.md), [download and upload translations](translate.md#downloading-and-uploading-translations), change their theme, etc.
+
+
+
+Note that some profile menu items are only available to users with specific [permissions](users.md#user-roles).
+
+A selector to change the current theme is available in the profile menu and in the [settings page](users.md#appearance). There are three theme options available:
+
+* Light.
+* Dark.
+* Match system (aligns with the theme used by the operating system).
+
+To change the theme, select the button corresponding to your preferred theme. The change will take effect immediately.
+
+## String list and search
+
+The left column displays the list of strings in the current project resource. Each string is represented by:
+
+* A colored square that identifies the string [status](#translation-status) (i.e. *Missing*, *Translated*, etc.).
+* The source string.
+* The approved translation or the most recent suggestion if available.
+
+
+
+Color legend:
+
+* **gray**: translation is missing.
+* **green**: string is translated.
+* **light-green**: string is pretranslated.
+* **orange**: translation has warnings.
+* **red**: translation has errors.
+
+When a string is selected in the sidebar, a small icon with four arrows is displayed near the checkbox: this can be used to show strings that surround the selected string in the [resource](glossary.md#resource), bypassing the current filter. This is often helpful to provide more context for the localization, especially when translating missing strings.
+
+
+
+### Search
+
+It’s possible to search within the currently selected project using the search field. Searches include strings and string IDs.
+
+
+
+Note that searches take active [filters](#filters) into account, for example a search would be performed only on missing strings if that filter was previously selected.
+
+Like in search engines, by default Pontoon will display matches that contain any of the search terms. For example, searching for `new tab` will match both `Open links in tabs instead of new windows` and `New Tab`.
+
+To search for an exact match, wrap the search terms in double quotes, e.g. `"new tab"`. On the other hand, to search for strings that contain double quotes, escape them with a backslash, e.g. `\"`.
+
+#### Search options
+
+In addition to the search filters listed below, Pontoon provides additional **search options**, allowing users to refine search results. Search options can be accessed by clicking the magnifying glass icon on the right side of the search box.
+
+
+
+Search options include:
+
+* **Match case**: exactly match the capitalization of the search term.
+* **Match whole word**: provides the same result as surrounding a word with double quotes, exactly matching the search term (case insensitive), and avoiding partial matches.
+* **Include string identifiers**: expand the search to include string identifiers (keys).
+* **Include rejected translations**: expand the search to include translations that have been rejected.
+* **Exclude source strings**: avoid searching for matches in source strings.
+
+When starting a search from the translation workspace, search options follow the user's [default search settings](users.md#default-search-options). If you clicked on a link performing a search, the menu will reflect the parameters used for that specific search — those might be different from your defaults.
+
+Clicking the `APPLY SEARCH OPTIONS` at the bottom of the panel will perform a new search with the selected options. To reset the current options back to the profile defaults, click `Restore default options`. To update the defaults, click `Change default search settings`, which opens the relevant section of the [settings page](users.md#default-search-options).
+
+### Filters
+
+#### Translation status
+
+Strings in Pontoon can be filtered by their status. A string can be in one of the following statuses:
+
+* **Translated**: string has an approved translation. The translation is saved to the localized file when using a [version control system](glossary.md#version-control-system) (VCS).
+* **Pretranslated**: string has been pretranslated but has not been reviewed. Unreviewed pretranslation are saved to the localized file when using a VCS.
+* **Warnings**: string contains issues classified as [warnings](translate.md#warnings).
+* **Errors**: string contains [critical issues](translate.md#errors).
+* **Missing**: string doesn’t have any approved translations.
+* **Unreviewed**: string has suggested translations that have not been reviewed yet by someone with the appropriate [permissions](glossary.md#permission). Note that, for both translated and missing strings, the suggested translation only exists within the Pontoon database and is not saved to the localized file when using a VCS.
+
+#### Extra filters
+
+In addition to statuses, additional filters can be used to further refine the list of strings. Extra filters include:
+
+* **Unchanged**: string is identical to the reference language (normally `en-US`).
+* **Empty**: string has a translation, but translation contains no content.
+* **Fuzzy**: string is marked as [fuzzy](glossary.md#fuzzy) in the localized file.
+* **Rejected**: string has rejected translations.
+* **Missing without Unreviewed**: string has `Missing` translation status and does not have `Unreviewed` translations.
+
+Filters can be accessed by clicking the icon on the left of the search field.
+
+
+
+At this point it’s possible to:
+
+* Click directly on the name of one of the filters. This will select and activate only this filter, and the search field placeholder will change accordingly. For example, clicking on `Missing` will show only missing strings, and the placeholder will read `Search in Missing`.
+* Click on one or more filter icons or user avatars (multiple filters can be applied at once). Hovering over the icons transforms the icon into check marks. Clicking an icon will select that filter and a new button `APPLY X FILTERS` will appear at the bottom of the panel, where `X` is the number of active filters.
+* Click `EDIT RANGE` on `TRANSLATION TIME` to select a time range. Pick one of the defaults (30 days, 7 days, 24 hours, 60 minutes), or use the date picker (or slider) to adapt the range. Click on `SAVE RANGE` to store the range as a filter. A new button `APPLY X FILTERS` will appear at the bottom of the panel, where `X` is the number of active filters.
+
+
+
+In this case 3 filters are selected.
+
+#### Tags
+
+For specific projects it’s also possible to filter strings based on *tags*. Tags are used to logically group resources based on their priority, allowing localizers to focus their work on important strings first, and project managers to better assess the overall localization status of the project.
+
+
+
+In this case, there are 10 tags defined for the project (highlighted in red). Near each tag there is a representation of the priority: like for projects, it goes from 5 stars (highest priority) to 1 star (lowest priority).
+
+Note: translation time, translation authors, and tags are not available when `All Projects` is selected as a [resource](glossary.md#resource).
+
+## Main editing space
+
+The main editing space in the middle column is where translation takes place.
+
+
+
+### String navigation
+
+The top of this space contains a string navigation interface. It’s possible to navigate sequentially through the strings by clicking the `PREVIOUS` or `NEXT` buttons located at the top of the editing space, or by using keyboard shortcuts (`ALT` + arrow down or up). A link to the current string can be copied to the clipboard using the `COPY LINK` button.
+
+### Source string
+
+Below the navigation interface, the user can view the source string, any comments present in the resource regarding the string, and the resource path where the string is located.
+In the same area, the `REQUEST CONTEXT or REPORT ISSUE` button can be used to request more information about the current string: it will focus the [COMMENTS section](##source-string-comments), and mention the project manager for the project.
+
+#### Context
+
+Sometimes you may want to investigate more context about a particular string through an external resource such as a [Version Control System](glossary.md#version-control-system). The `CONTEXT` information provided underneath the source string shows the identifier, file, and project for the string — allowing you to find the string within the codebase of the project. For example, for some Mozilla projects these can be used to [track strings to bugs](https://mozilla-l10n.github.io/localizer-documentation/tools/mercurial/tracking_back_string_to_bug.html).
+
+
+
+### Editor
+
+The editor is located in the middle section of the column, and it’s where users can input or edit their translations.
+
+In the lower-right side of the editing space, it’s possible to `COPY` the source string to the editor, `CLEAR` the area where translations are typed, and `SUGGEST` or `SAVE` the translation by clicking the corresponding button. This area is also used to [display warnings and errors](translate.md#quality-checks) when submitting a translation.
+
+In the lower-left side:
+
+* Clicking the gear icon allows users to toggle `Translation Toolkit checks` or `Make suggestions`, and navigate to the user settings. Note that access to some settings is restricted by [user permissions](users.md#user-roles).
+* Clicking the keyboard icon displays a list of available shortcuts.
+* The numbers displayed to the right of the keyboard icon (e.g. `50|59`) are the number of characters in the target and source string.
+
+#### Read-only projects
+
+A project could be enabled in *read-only mode* for some locales: their translations will be available to other languages in the `LOCALES` tab, but it won’t be possible to change or submit translations directly in Pontoon. In this case, a note is displayed in the bar below the editor, and all other controls are hidden.
+
+
+
+### Translation list
+
+The space below the editor displays the list of [translations](glossary.md#translation) for the current string.
+
+Each entry contains:
+
+* The name of the translator, their profile picture (linking to their profile page) and their banner (see [User banners](#user-banners)).
+* How long ago the entry was submitted (hover over to see the full date and time as a tooltip).
+* The translation.
+* Icons indicating translation status (see below).
+* [Translation comments](glossary.md#comment).
+
+Icons to the right indicate the [status](#translation-status) of each translation:
+
+* The solid green circle with checkmark indicates that the translation has been approved.
+* The outlined lime green circle with checkmark indicates a pretranslation that has not yet been reviewed.
+* If both icons are gray, translation has been suggested but not yet reviewed.
+* The red cross indicates that the translation has been rejected. The entire element will look opaque.
+* The trashcan, available only for rejected translations, can be used to completely delete a translation. Those with the contributor role can only remove their own translations, while those with a translator permissions can delete anyone’s.
+
+
+
+In the screenshot above, the first item is the approved translation (green checkmark), while the other two are rejected suggestions.
+
+#### User banners
+
+User banners provide immediate context about a user to other community members. They indicate either the role of the user, or that the user is new to Pontoon. Banners are displayed at the bottom of the user's avatar.
+
+
+
+The available user banners are:
+
+* `MNGR` for [team managers](users.md#user-roles).
+* `TRNSL` for [translators](users.md#user-roles).
+* `PM` for [project managers](users.md#user-roles).
+* `ADMIN` for [administrators](users.md#user-roles).
+* `NEW` for users who have joined within the last 3 months.
+
+User banners will also appear in translation comments (see below).
+
+#### Translation comments
+
+By clicking the `COMMENT` button it’s possible to add a **translation comment** to this specific translation. To mention another user in the comment, start typing `@` followed by their name.
+
+If there is already a comment associated with a string, the button will display the number of comments (e.g. `1 COMMENT` for the first rejected suggestion).
+
+#### Viewing translation differences
+
+The `DIFF` option appears if there are multiple translations for one string. Toggling `DIFF` compares the text to the current approved translation, or the most recent suggestion if no translation has been approved yet. Text highlighted in green indicates content that has been added, while strikethrough text in red indicates removed content. Toggling `DIFF` again will display the original string.
+
+
+
+## Fluent - FTL files
+
+When working on FTL (Fluent) files, the editing space will look slightly different.
+
+
+
+In the example above, the string has a `value` and an attribute `title`. Both are displayed in the source section (highlighted in red), and available as separate input fields in the editor (highlighted in orange).
+
+The following image is an example of a string with plurals: while English only has two forms, plural and singular, other locales can have a different number of plural forms. In this case, Russian has three forms (highlighted in orange).
+
+
+
+In the bottom left corner, the FTL button (highlighted in yellow) allows to switch between the standard UI (*Simple FTL mode*) and the *Advanced FTL mode*, where it’s possible to edit the original syntax directly, as you would in a text editor. For details on the Fluent syntax, see [Fluent for localizers](https://mozilla-l10n.github.io/localizer-documentation/tools/fluent/index.html).
+
+
+
+Note that the FTL button’s text is green when in *Advanced FTL mode*.
+
+## Translation tools and comments
+
+Built-in translation tools are located in the rightmost column.
+
+### Terminology
+
+The `TERMS` tab shows the definition and translation of a term, in case the source string includes matches with the built-in [terminology](glossary.md#terminology). The matching term is also highlighted in the source string. A popup appears on click showing the definition and translation for a term.
+
+
+
+### Source string comments
+
+The `COMMENTS` tab is used to display existing **source string comments**, or add new ones. Source string comments, unlike translation comments, are associated with the string: it’s possible to have a comment in this section even if the string doesn’t have any suggestion or translation yet.
+
+They’re designed for team members to have a conversation about the source string, for example to clarify its meaning, or to get more information from project managers.
+
+Administrators can pin or unpin a source string comment: this pinned comment will be displayed along existing comments in the editing area as `PINNED COMMENT`, and users will [receive a notification](notifications.md#comments).
+
+
+
+The screenshot above shows a pinned comment, and the command to unpin it.
+
+### Machinery
+
+Machinery shows possible translations from a variety of sources. These sources include:
+
+* [Pontoon’s internal translation memory](translate.md#downloading-and-uploading-translations).
+* [Google Translate](https://translate.google.com).
+* [SYSTRAN](https://www.systran.net/).
+* [Caighdean](https://github.com/kscanne/caighdean).
+* [Bing Translator](https://www.bing.com/translator) (not currently enabled on pontoon.mozilla.org).
+
+In addition, the user has the ability to search for translations containing words via [`Concordance search`](#concordance-search).
+
+In the tab, the number of entries is visible alongside the `MACHINERY` title in white. If any of the machinery matches are from translation memory, the number of matches will appear separately in green. For example, the screenshot below shows `2+1`, where the green `2` represents the two matches from translation memory and the `1` represents a machinery entry from Google Translate.
+
+
+
+At the top of each entry, a diff view compares the current source string and the source string from the machinery entry. Strikethrough text highlighted in red indicates text that is present in the source string but not in the machinery source string, while text highlighted in green indicates text available only in the machinery source string.
+
+To the right of the entry, the number in green shows the percent match between the machinery source string and the current source string. The higher the percentage, the more likely machinery is to be useful; a 100% match indicates that the sources for the current string and for the machinery string are identical.
+
+The origin of the machinery entry is listed in gray above the source string. Clicking the gray text will open the origin in a new window. The green superscript to the right indicates the number of matches for the entry in the translation memory.
+
+Be careful when using the machinery tab as suggestions may not match the source string for the project being translated. Even if the source strings match, the context in which strings are used may not be the same. This could lead to incorrect or unnatural translations. Always keep the meaning and purpose of the string being translated in mind when using the machinery tab.
+
+#### Large language model (LLM) integration
+
+Pontoon will show a dropdown labeled `AI` for all locales that have Google Translate available as a translation source. This feature refines the Google Translate output using an LLM. Opening this dropdown will reveal three options:
+
+* `REPHRASE`: Generate an alternative to this translation.
+* `MAKE FORMAL`: Generate a more formal version of this translation.
+* `MAKE INFORMAL`: Generate a more informal version of this translation.
+
+
+
+After selecting an option, the revised translation will replace the original suggestion. Once a new translation is generated, another option `SHOW ORIGINAL` will be available in the dropdown menu. Selecting it will revert to the original suggestion.
+
+
+
+#### Concordance search
+
+Concordance search allows users to search across all projects in Pontoon. Users can search for translations using strings in either source or target language. Matching results are displayed with the source string, translation, and project name; clicking a result will automatically fill the translation into the editor. Note that the search does not need to be related to the current string or project.
+
+
+
+### Locales
+
+The locales tab shows approved translations from Pontoon projects in other [locales](glossary.md#locale).
+
+
+
+Next to the `LOCALES` title, the number of available entries is visible. The number for preferred locales is green, while the number for all other locales is in gray.
+
+Users can select locales to appear at the top of their Locales tab as a preferred locale. To add a locale to the preferred locale list, access the [user settings](users.md#locale-settings) page.
+
+Entries in the `LOCALES` tab above the green line are preferred locales. Non-preferred locales are displayed below the green line, sorted alphabetically by language name.
+
+Each row displays the translation for the source string in the selected locale. Above each entry, the language name is visible in gray, while the locale code is displayed in green.
+
+The `LOCALES` tab is useful for seeing what general style choices are made by other localization communities. When encountering a difficult string, a translator can use other locales as a source of inspiration.
+
+Note that, when using the `LOCALES` tab, the translator should always opt for fluency in their own locale. Languages vary linguistically on many levels. The locales tab can be extremely useful, but should be used carefully, and rarely as the sole translation resource for translation.
+
+## Smaller screens
+
+The translation workspace is responsive, which means the layout will adapt to smaller screens. Everything you do on your desktop computer or laptop, you can also do on your phone or tablet: review strings, fix typos or even translate a few strings on the go.
+
+
diff --git a/documentation/docs/localizer/users.md b/documentation/docs/localizer/users.md
new file mode 100644
index 0000000000..e55553d32d
--- /dev/null
+++ b/documentation/docs/localizer/users.md
@@ -0,0 +1,145 @@
+# User Accounts & Settings
+
+## Creating an account
+
+While Pontoon can be configured to use [different login systems](../dev/deployment.md#environment-variables) (Django, GitHub, etc.), the Mozilla instance hosted at [pontoon.mozilla.org](https://pontoon.mozilla.org/) uses Firefox accounts.
+
+To create an account, click on the `Sign In` button in the top right corner and follow the instructions.
+
+## User settings
+
+User settings can be accessed by:
+
+* Clicking the user avatar in the top right corner, and selecting `Settings` from the dropdown menu.
+* Opening the `/settings` URL directly (e.g. [pontoon.mozilla.org/settings](https://pontoon.mozilla.org/settings/)).
+* Using the `CHANGE SETTINGS` button in the [Profile page](profile.md).
+
+
+
+### Profile picture
+
+The profile picture can be set or updated on [Gravatar](http://gravatar.com/) by clicking the image displayed at the top of the settings page (when hovered, the picture will display an `Update profile picture` message).
+
+### Personal information
+
+In this section it’s possible to update the display name and other personal information:
+
+* `Display name`: it’s the name displayed in Pontoon, for example when submitting a translation or suggestion. It’s also used as the author name when committing translations to version control system (i.e. git or hg repositories).
+* `Username`: this is currently used to generate the URL for the [Profile page](profile.md) (e.g. `https://pontoon.mozilla.org/contributors/USERNAME/`). If not provided, a hash will be used instead of the username.
+* `Bio`: a short text that will be displayed in the Profile page.
+
+### Email
+
+In this section it’s possible to update the display name and other personal information:
+
+* `Contact email address`: if provided, this email address will be used for email communications and displayed in the Profile page instead of the login email address.
+* `News and updates`: if enabled, you will get the latest updates about localization at Mozilla, announcements about new Pontoon features, invitations to contributor events and more.
+* `Monthly activity summary`: if enabled, you will get an email summary of your personal activity and the activity within your teams for the previous month.
+
+### Notification subscriptions
+
+Pontoon can send internal notifications to users for specific events. All notifications are enabled by default, but can be disabled by using the corresponding checkbox.
+
+Additionally, for each notification type, users can choose to receive email updates in a digest format. These email digests can be scheduled to arrive either daily or weekly, depending on the user’s selection.
+
+For more information about this topic, refer to the page dedicated to [notifications](notifications.md).
+
+### External accounts
+
+In this section it’s possible to specify the username used in external accounts, like GitHub or Bugzilla. If provided, this information will be displayed in the Profile page.
+
+### Visibility of data on the Profile page
+
+Users can determine the visibility of fields containing personal information — like email address or external accounts — and statistics about their contribution. From the smallest audience to the largest, a field can be visible to:
+
+* `Translators`: these are users with translator permissions in Pontoon, independently from the locale. The rationale is that translators need to have access to specific information to either contact a contributor during review, or check stats about their previous contributions.
+* `Logged-in users`: these are users logged-in to Pontoon, independently from their permissions.
+* `Public`: this includes all users and not logged-in visitors.
+
+These are the available data fields:
+
+* `Email address`: by default, this field is only visible to translators. Visibility can be expanded to all logged-in users, but it’s always hidden to visitors to reduce the risk of spam. This setting is ignored for team and project managers, as their email address is always visible to logged-in users.
+* `External accounts`: by default, this data is only visible to translators, but it can be made public.
+* `Approval rate` and `Self-approval rate`: by default, these fields are set as public, but can be limited to translators.
+
+### Appearance
+
+The user can chose between a light and dark combination of colors for Pontoon. There are three theme options available:
+
+* Light.
+* Dark.
+* Match system (aligns with the theme used by the operating system).
+
+To change the theme, select the button corresponding to your preferred theme. The change will take effect immediately.
+
+### Editor
+
+`Translation Toolkit Checks` (checks for number of sentences, placeholders, HTML tags, punctuation, etc.) are performed when saving a translation. For more information about quality checks, see [this document](translate.md#quality-checks).
+
+`Make suggestions` allows a translator or a team manager to submit suggestions instead of translations. This setting is also displayed to users with translator permissions.
+
+### Default search options
+
+Users can configure default search options to use when searching for strings in the translation workspace or the [Translation Search page](search.md). The following options can be enabled by default:
+
+* **Match case**: the search will be case-sensitive.
+* **Match whole word**: the search will match only complete words, avoiding partial matches.
+* **Search in string identifiers**: the search will also match against string keys/identifiers.
+* **Include rejected translations**: the search will also include translations that have been rejected.
+* **Exclude source strings**: the search will not look for matches in source strings.
+
+Note that the current search options can always be overridden directly in the search panel, which also provides a `Restore default options` link to reset back to these saved defaults.
+
+### Locale settings
+
+It’s possible to set the default homepage displayed when visiting Pontoon as a logged-in user. Current options are:
+
+* Default homepage (Pontoon’s homepage).
+* [A Team page](teams-projects.md#team-page).
+
+`Preferred source locales` can be used to display a different source locale when translating. In Mozilla projects, the source locale is always English (en-US).
+
+`Preferred locales` can be used to display a specific group of locales before others in the `LOCALES` tab when translating strings. In the image below, the user chose to display `fr` and `es-ES` before other translations — ordered alphabetically based on the locale name. Since they’re both available the tab displays 2+118, meaning 2 preferred locales plus all others.
+
+
+
+### Account removal
+
+Users can delete their account by scrolling to the `Account Management` section, where a button reading `Delete Account` is located. Once clicked, the user will need to
+confirm once again that they intend to delete their account. Upon confirming, the user is signed out and won’t be able to access the account again. Their data will be removed
+and any translations previously attributed to them will be attributed as **Imported**.
+
+
+
+## User roles
+
+There are five user roles in Pontoon:
+
+* **Contributors** can only submit suggestions. This is the default role for new users.
+* **Translators** can submit translations directly in a specific locale, and review other contributors’ suggestions.
+* **Team Managers** can perform the same actions as translators, but also manage other users and update their permissions.
+* **Project Managers** don’t have translator permissions, but they act as the point of contact for a specific project. Their name is displayed in the header of Project and Localization pages, and using the `REQUEST CONTEXT or REPORT ISSUE` function will tag them in a comment.
+* **Administrators** can manage Pontoon, e.g. adding or removing projects, and act as Team Managers for all locales.
+
+## Managing permissions
+
+A Team Manager can upgrade other users’ permissions within a locale. To manage users, open the team page and select the `PERMISSIONS` tab (it will only be visible to Team Managers and Administrators).
+
+By default there’s only a `General` section: permissions defined here will apply to all projects, but can be overridden by custom project permissions.
+
+
+
+To move a user to a different column, hover the email address: arrows will appear to move the element to the left or right. Note that a user needs to log in at least once in Pontoon in order to upgrade their permission – simply having an account is not sufficient.
+
+Use the `SAVE` button to store the configuration before leaving this window.
+
+By default, the `TEAM CONTRIBUTORS` column will only include users that have already submitted suggestions for this locale. Click `ALL USERS` (highlighted in red) to display all existing users, then use the search field to narrow down the list.
+
+By clicking `ADD CUSTOM PERMISSIONS PER PROJECT` (highlighted in orange), it’s possible to add specific permissions for a project. This can be useful to make sure that only some users can submit translations for a specific project, for example if it’s maintained by one person.
+
+
+
+Note that:
+
+* The list of translators defined for a specific project overrides the list defined in the `General` section. If a user needs to be able to translate all projects, they need to be listed in all custom permissions on top of the `General` section.
+* It’s not possible to override Team Managers, as they will always be able to submit translations in any of the projects available for their locale.
diff --git a/documentation/zensical.toml b/documentation/zensical.toml
new file mode 100644
index 0000000000..5a12aaa68e
--- /dev/null
+++ b/documentation/zensical.toml
@@ -0,0 +1,108 @@
+# Pontoon docs configuration for Zensical
+
+[project]
+site_name = "Pontoon Documentation"
+site_description = "Pontoon is Mozilla's translation management system. This documentation covers everything from translating strings to deploying your own instance."
+site_url = "https://pontoon.mozilla.org/docs/"
+repo_url = "https://github.com/mozilla/pontoon"
+repo_name = "mozilla/pontoon"
+edit_uri = "edit/main/documentation/docs/"
+
+nav = [
+ { "Home" = "index.md" },
+
+ { "Localizer Guide" = [
+ { "Overview" = "localizer/index.md" },
+ { "How to Translate" = "localizer/translate.md" },
+ { "Translation Workspace" = "localizer/translation-workspace.md" },
+ { "Team & Project Pages" = "localizer/teams-projects.md" },
+ { "Translation Search" = "localizer/search.md" },
+ { "User Accounts & Settings" = "localizer/users.md" },
+ { "Notifications" = "localizer/notifications.md" },
+ { "Profile Page" = "localizer/profile.md" },
+ { "Glossary" = "localizer/glossary.md" }
+ ]},
+
+ { "Admin Guide" = [
+ { "Overview" = "admin/index.md" },
+ { "Adding a New Project" = "admin/adding-new-project.md" },
+ { "Adding a New DB Project" = "admin/adding-new-db-project.md" },
+ { "Adding a New Locale" = "admin/adding-new-locale.md" },
+ { "Managing Pretranslation" = "admin/managing-pretranslation.md" },
+ { "Messaging Center" = "admin/messaging-center.md" },
+ { "Renaming a Localization File" = "admin/renaming-file.md" },
+ { "Renaming a Project" = "admin/renaming-project.md" },
+ { "Managing Users" = "admin/managing-users.md" },
+ { "Adding Terminology" = "admin/adding-terminology.md" }
+ ]},
+
+ { "Developer Guide" = [
+ { "Overview" = "dev/index.md" },
+ { "First Contribution" = "dev/first-contribution.md" },
+ { "Developer Setup" = "dev/developer-setup.md" },
+ { "Contributing Guidelines" = "dev/contributing.md" },
+ { "Feature Development Process" = "dev/feature-development-process.md" },
+ { "Deployment" = "dev/deployment.md" },
+ { "Maintenance" = "dev/maintenance.md" },
+ ]}
+]
+
+[project.theme]
+language = "en"
+logo = "assets/pontoon-logo.svg"
+favicon = "assets/pontoon-logo.svg"
+features = [
+ "navigation.footer",
+ "navigation.tabs",
+ "navigation.sections",
+ "navigation.expand",
+ "navigation.path",
+ "navigation.top",
+ "navigation.instant",
+ "search.highlight",
+ "content.action.edit", # Edit this page
+ "content.action.view", # View source of this page
+ "content.code.copy",
+ "toc.follow"
+]
+
+# If you confirm the repository settings syntax you want to use in Zensical,
+# you can then re-enable "content.action.edit" above.
+
+[[project.theme.palette]]
+media = "(prefers-color-scheme: light)"
+scheme = "default"
+toggle.icon = "lucide/sun"
+toggle.name = "Switch to dark mode"
+
+[[project.theme.palette]]
+media = "(prefers-color-scheme: dark)"
+scheme = "slate"
+toggle.icon = "lucide/moon"
+toggle.name = "Switch to light mode"
+
+[[project.extra.social]]
+icon = "fontawesome/brands/github"
+link = "https://github.com/mozilla/pontoon"
+
+[project.markdown_extensions.pymdownx.highlight]
+anchor_linenums = true
+
+[project.markdown_extensions.pymdownx.tabbed]
+alternate_style = true
+
+[project.markdown_extensions.pymdownx.emoji]
+emoji_index = "zensical.extensions.emoji.twemoji"
+emoji_generator = "zensical.extensions.emoji.to_svg"
+
+[project.markdown_extensions.toc]
+permalink = true
+
+# Enabled without extra options in mkdocs.yml:
+[project.markdown_extensions.admonition]
+[project.markdown_extensions.pymdownx.details]
+[project.markdown_extensions.pymdownx.superfences]
+[project.markdown_extensions.pymdownx.inlinehilite]
+[project.markdown_extensions.pymdownx.snippets]
+[project.markdown_extensions.attr_list]
+[project.markdown_extensions.md_in_html]
diff --git a/pontoon/base/templates/allauth/layouts/base.html b/pontoon/base/templates/allauth/layouts/base.html
index 88c40e659b..b8bf445348 100644
--- a/pontoon/base/templates/allauth/layouts/base.html
+++ b/pontoon/base/templates/allauth/layouts/base.html
@@ -151,7 +151,7 @@
{`There’s a wide variety of tools to help you with translations,
some of which we didn’t mention in this tutorial. For more
topics of interest for localizers at Mozilla, please have a look
- at the Localizer Documentation.`}