1 files changed, 129 insertions, 0 deletions
diff --git a/intl/l10n/docs/crosschannel/content.rst b/intl/l10n/docs/crosschannel/content.rst
new file mode 100644
index 0000000000..1a1c8af879
--- /dev/null
+++ b/intl/l10n/docs/crosschannel/content.rst
@@ -0,0 +1,129 @@
+=====================
+Cross-channel Content
+=====================
+
+When creating the actual content, there's a number of questions to answer.
+
+#. Where to take content from?
+#. Which content to take?
+#. Where to put the content?
+#. What to put into each file?
+
+Content Sources
+---------------
+
+The content of each revision in ``gecko-strings`` corresponds to a given
+revision in each original repository. For example, we could have
+
++------------------+--------------+
+| Repository       | Revision     |
++==================+==============+
+| mozilla-central  | 4c92802939c1 |
++------------------+--------------+
+| mozilla-beta     | ace4081e8200 |
++------------------+--------------+
+| mozilla-release  | 2cf08fbb92b2 |
++------------------+--------------+
+| mozilla-esr68    | 2cf9e0c91d51 |
++------------------+--------------+
+| comm-central     | 3f3fc2c0d804 |
++------------------+--------------+
+| comm-beta        | f95a6f4408a3 |
++------------------+--------------+
+| comm-release     | dc2694f035fa |
++------------------+--------------+
+| comm-esr68       | d05d4d87d25c |
++------------------+--------------+
+
+The assumption is that there's no content that's shared between ``mozilla-*`` and
+``comm-*``, so we can just convert one repository and its branches at a time.
+
+Covered Content
+---------------
+
+Which content is included in ``gecko-strings`` is
+controlled by the project configurations of each product, on each branch.
+Currently, those are :file:`browser/locales/l10n.toml` and
+:file:`mobile/android/locales/l10n.toml` in ``mozilla-central``.
+
+Created Content Structure
+-------------------------
+
+The created content is laid out in the directory in the same structure as
+the files in ``l10n-central``. The localizable files end up like this:
+
+.. code-block:: text
+
+   browser/
+     browser/
+       browser.ftl
+   chrome/
+     browser.properties
+   toolkit/
+     toolkit/
+       about/aboutAbout.ftl
+
+This matches the file locations in ``mozilla-central`` with the
+:file:`locales/en-US` part dropped.
+
+The project configuration files are also converted and added to the
+created file structure. As they're commonly in the :file:`locales` folder
+which we strip, they're added to the dedicated :file:`_configs` folder.
+
+.. code-block:: bash
+
+   $ ls _configs
+   browser.toml   devtools-client.toml  devtools-shared.toml
+   mobile-android.toml  toolkit.toml
+
+
+L10n File Contents
+------------------
+
+Let's assume we have a file to localize in several revisions with different
+content.
+
+== ======= ==== =======
+ID central beta release
+== ======= ==== =======
+a  one     one  one
+b          two  two
+c  three
+d  four    old  old
+== ======= ==== =======
+
+The algorithm then creates content, taking localizable values from the left-most
+branch, where *central* overrides *beta*, and *beta* overrides *release*. This
+creates content as follows:
+
+== =======
+ID content
+== =======
+a  one
+b  two
+c  three
+d  four
+== =======
+
+If a file doesn't exist in one of the revisions, that revision is dropped
+from the content generation for this particular file.
+
+.. note::
+
+   The example of the forth string here highlights the impact that changing
+   an existing string has. We ship one translation of *four* to central,
+   beta, and release. That's only a good idea if it doesn't matter which of the
+   two versions of the English copy got translated.
+
+Project configurations
+----------------------
+
+The TOML files for project configuration are processed, but not unified
+across branches at this point.
+
+.. note::
+
+   The content of the ``-central`` branch determines what's localized
+   from ``gecko-strings``. Thus that TOML file needs to include all
+   directories across all branches for now. Removing entries requires
+   that the content is obsolete on all branches in cross-channel.