From bdcb688744ca307e6c3f87d30040e2c67643576c Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Oct 03 2018 16:33:55 +0000 Subject: add PO POT repo structure --- diff --git a/po-pot-repo-structure.md b/po-pot-repo-structure.md new file mode 100644 index 0000000..3b377c7 --- /dev/null +++ b/po-pot-repo-structure.md @@ -0,0 +1,411 @@ +# PO POT repos structure + +Goal: Enable translations on the Fedora Docs site. + +Simply put, the translation process works in three steps: + + 1. Extract strings from the English sources and produce POT files + 2. Translators translate these POT files and produce PO files + 3. We consume these PO files to construct translated sources, and finally to build the translated website + +This step is about storing the POT and PO files. + +**Antora principal**: Source structure in git repositories is independent from the website structure. More details: + +The content is divided into components (spaces with their own menu). Each component can have multiple versions, and also multiple modules. The primary function of modules is an ability to store different parts of components in different git repositories. But they can be also stored in a single repository. One repository can even hold multiple components. And moving components or modules between repositories has no influence on the output. **We need to keep this principle in mind when designing the PO and POT repository structure** — moving source between repositories can't change the concent for translators. That's why we need to organize the PO and POT files not according to the repositories, but according to the components, modules, and versions. + + +## Antora content structure: + +Two possible views at the same structure: + +``` + site / components / modules / versions / pages + OR + site / components / versions / modules / pages +``` + +## Actual example: + +``` + Fedora Docs / fedora / ROOT / f28 / pages + Fedora Docs / fedora / ROOT / f29 / pages + Fedora Docs / fedora / release-notes / f28 / pages + Fedora Docs / fedora / release-notes / f29 / pages + Fedora Docs / fedora / install-guide / f28 / pages + Fedora Docs / fedora / install-guide / f29 / pages + Fedora Docs / fedora / system-administrators-guide / f28 / pages + Fedora Docs / fedora / system-administrators-guide / f29 / pages + Fedora Docs / mindshare / ROOT / master / pages + Fedora Docs / fesco / ROOT / master / pages +``` + +## Possible PO and POT repository structures: + +Two options below, holding the structure above + +### Option 1: three repos + +There is a repo for every component, modules are directories in their repos. + +**Repo: fedora** + +``` + |-- ROOT + | |-- f28 + | | |-- po + | | | |-- cs + | | | | `-- pages.po + | | | |-- fr + | | | | `-- pages.po + | | | `-- jp + | | | `-- pages.po + | | `-- pot + | | `-- pages.pot + | `-- f29 + | |-- po + | | |-- cs + | | | `-- pages.po + | | |-- fr + | | | `-- pages.po + | | `-- jp + | | `-- pages.po + | `-- pot + | `-- pages.pot + |-- install-guide + | |-- f28 + | | |-- po + | | | |-- cs + | | | | `-- pages.po + | | | |-- fr + | | | | `-- pages.po + | | | `-- jp + | | | `-- pages.po + | | `-- pot + | | `-- pages.pot + | `-- f29 + | |-- po + | | |-- cs + | | | `-- pages.po + | | |-- fr + | | | `-- pages.po + | | `-- jp + | | `-- pages.po + | `-- pot + | `-- pages.pot + |-- release-notes + | |-- f28 + | | |-- po + | | | |-- cs + | | | | `-- pages.po + | | | |-- fr + | | | | `-- pages.po + | | | `-- jp + | | | `-- pages.po + | | `-- pot + | | `-- pages.pot + | `-- f29 + | |-- po + | | |-- cs + | | | `-- pages.po + | | |-- fr + | | | `-- pages.po + | | `-- jp + | | `-- pages.po + | `-- pot + | `-- pages.pot + `-- system-administration-guide + |-- f28 + | |-- po + | | |-- cs + | | | `-- pages.po + | | |-- fr + | | | `-- pages.po + | | `-- jp + | | `-- pages.po + | `-- pot + | `-- pages.pot + `-- f29 + |-- po + | |-- cs + | | `-- pages.po + | |-- fr + | | `-- pages.po + | `-- jp + | `-- pages.po + `-- pot + `-- pages.pot +``` + +**Repo: fesco** + +``` + `-- ROOT + `-- master + |-- po + | |-- cs + | | `-- pages.po + | |-- fr + | | `-- pages.po + | `-- jp + | `-- pages.po + `-- pot + `-- pages.pot +``` + +**Repo: mindshare** + +``` + `-- ROOT + `-- master + |-- po + | |-- cs + | | `-- pages.po + | |-- fr + | | `-- pages.po + | `-- jp + | `-- pages.po + `-- pot + `-- pages.pot +``` + +### Option 2: six repos + +Here, every module is a repository. +The name is "component-module", or just "component" if the module is "ROOT". + +**Repo: fedora** + +``` + + |-- f28 + + | |-- po + + | | |-- cs + + | | | `-- pages.po + + | | |-- fr + + | | | `-- pages.po + + | | `-- jp + + | | `-- pages.po + + | `-- pot + + | `-- pages.pot + + `-- f29 + + |-- po + + | |-- cs + + | | `-- pages.po + + | |-- fr + + | | `-- pages.po + + | `-- jp + + | `-- pages.po + + `-- pot + + `-- pages.pot + +``` + +**Repo: fedora-install-guide** + +``` + + |-- f28 + + | |-- po + + | | |-- cs + + | | | `-- pages.po + + | | |-- fr + + | | | `-- pages.po + + | | `-- jp + + | | `-- pages.po + + | `-- pot + + | `-- pages.pot + + `-- f29 + + |-- po + + | |-- cs + + | | `-- pages.po + + | |-- fr + + | | `-- pages.po + + | `-- jp + + | `-- pages.po + + `-- pot + + `-- pages.pot + +``` + +**Repo: fedora-release-notes** + +``` + + |-- f28 + + | |-- po + + | | |-- cs + + | | | `-- pages.po + + | | |-- fr + + | | | `-- pages.po + + | | `-- jp + + | | `-- pages.po + + | `-- pot + + | `-- pages.pot + + `-- f29 + + |-- po + + | |-- cs + + | | `-- pages.po + + | |-- fr + + | | `-- pages.po + + | `-- jp + + | `-- pages.po + + `-- pot + + `-- pages.pot + +``` + +**Repo: fedora-system-administration-guide** + +``` + + |-- f28 + + | |-- po + + | | |-- cs + + | | | `-- pages.po + + | | |-- fr + + | | | `-- pages.po + + | | `-- jp + + | | `-- pages.po + + | `-- pot + + | `-- pages.pot + + `-- f29 + + |-- po + + | |-- cs + + | | `-- pages.po + + | |-- fr + + | | `-- pages.po + + | `-- jp + + | `-- pages.po + + `-- pot + + `-- pages.pot + +``` + +**Repo: fesco** + +``` + + `-- master + + |-- po + + | |-- cs + + | | `-- pages.po + + | |-- fr + + | | `-- pages.po + + | `-- jp + + | `-- pages.po + + `-- pot + + `-- pages.pot + +``` + +**Repo: mindshare** + +``` + + `-- master + + |-- po + + | |-- cs + + | | `-- pages.po + + | |-- fr + + | | `-- pages.po + + | `-- jp + + | `-- pages.po + + `-- pot + + `-- pages.pot + +``` \ No newline at end of file