Update README

Author: ynojima

README.md

@@ -1,50 +1,63 @@
 # ja-quarkusio
 
-Localization project for [quarkusio.github.io](https://github.com/quarkusio/quarkusio.github.io) (The repository for [quarkus.io website](https://quarkus.io))
+Localization project for [https://github.com/quarkusio/quarkusio.github.io](https://github.com/quarkusio/quarkusio.github.io) (The repository for [quarkus.io website](https://quarkus.io))
 
 Localized site: [https://ja-quarkusio.surge.sh/](https://ja-quarkusio.surge.sh)
 
-## Translation workflow
+## Localization architecture
 
-Original [quarkusio.github.io](https://github.com/quarkusio/quarkusio.github.io) is built with Jekyll, and its contents are written in asciidoctor (.adoc) files.
-ja-quarkusio extracts texts with [po4a](https://po4a.org/) utility, machine-translates with deepL, write back, and build a localized site.
-Most workflow are automated by GitHub Actions except manual post-editing(translation). If you are interested in contributing localization,
-please translate .po files, and submit a pull request.
+Original [quarkusio.github.io](https://github.com/quarkusio/quarkusio.github.io) is built with Jekyll, 
+and most of its contents are written in asciidoctor (.adoc) files.
+ja-quarkusio extracts texts to po files with [po4a](https://po4a.org/) utility, translates, 
+write back to asciidoctor files, and build a localized site.
+Most workflow including pre-translation by DeepL API are automated by GitHub Actions. 
+Translators can focus on post-editing to improve fluency.
+If you are interested in contributing localization, please edit .po files, and submit a pull request.
 
-### Prerequisites
+![translation-workflow](internal/docs/images/translation-workflow.png)
 
-All you need for your local environment is a CAT Tool like [POEdit](https://poedit.net/), which run on Win/Mac/Linux.
+### .adoc files localization
 
-### Extracting texts from original repository
+#### sync workflow
 
-ja-quarkusio extracts texts with [po4a-updatepo](https://po4a.org/) utility from .adoc files to .adoc.po files, which saved in 
-in [l10n/po](l10n/po) directory.
-ja-quarkusio GitHub repository has a [GitHub Actions' periodic workflow](.github/workflows/sync-upstream.yml) 
-to extract texts from .adoc files stored in upstream submodule, 
-which points [quarkusio.github.io](https://github.com/quarkusio/quarkusio.github.io) repository.
+ja-quarkusio GitHub repository has a GitHub Actions workflow which checks upstream repository(submodule) update, 
+extracts texts from upstream .adoc files to [.adoc.po files](l10n/po), pre-translate with a translation memory 
+and the DeepL API.
 
-### Translating .po files
+#### Translating .po files
 
 .po files in [l10n/po](l10n/po) directory need to be translated. 
 .po file is a file format commonly used for software internationalization, and many CAT software and SaaS can read/write.
-While generating .po files, texts are pre-filled with translation memory and machine translation. 
-Please correct inappropriate sentences if needed.
+[POEdit](https://poedit.net/), which run on Windows/Mac/Linux is a good candidate.
+Since .po files are pre-filled with machine translation with "fuzzy" mark, 
+please remove "fuzzy" mark and correct inappropriate sentences if needed.
 
-### Applying translated texts
+#### Build a localized site
 
-Now you are ready to apply translated texts to .adoc files. With the command below, translated source tree are formed in `translated` directory.
+When you send a pull-request, GitHub Actions workflow automatically apply translations in .po files to .adoc files,
+build a localized site and deploy it to surge.sh with preview domain. When the deploy finish, GitHub Actions comment 
+the URL to the pull-request. Reviewers can check the deployed site for review.
+When the pull-request is merged into `master`, it is automatically deployed to the production site.
+
+#### Build a localized site locally
+
+If you would like to build a site locally, run:
 
 ```
 bin/apply-translation
+bin/exec-jekyll
 ```
 
-### Build a translated site
+The site is build in `doc` directory.
 
-You can build a translated site from `translated` directory with:
+### HTML templates localization
 
-```
-bin/exec-jekyll
-```
+Most contents of [quarkus.io](https://quarkus.io) are in .adoc files, but a few texts are in its HTML templates.
+Since HTML templates cannot be parsed with [po4a](https://po4a.org/) utility, this localization project repository has their
+localized copies in the [l10n/override](l10n/override) directory. When the templates in the upstream repository are 
+updated, GitHub Actions workflow automatically create a issue to let you know. 
+Please refer the [l10n/stats/override.csv](l10n/stats/override.csv) to check which files are updated, and update the override files 
+to keep it up to date.
 
 ## Contributing