diff --git a/docs/i18n.md b/docs/i18n.md
index 471eb88f1eb7..c91f29e63dfe 100644
--- a/docs/i18n.md
+++ b/docs/i18n.md
@@ -47,58 +47,66 @@ This will generate a full link with HTML `For further information <a href="https
 Use the `<%: text to translate %>` as documented on [Templates](./Templates.md)
 
 ### Translations in Lua controller code and Lua CBIs
-As hinted at in the Templates doc, the `%:` is actually invoking a `translate()` function.
+As hinted at in the Templates doc, the `%:` invokes a `translate()` function.
 In most controller contexts, this is already available for you, but if necessary, is available for include in `luci.i18n.translate`
 
 
 ## Translation files
 Translations are saved in the folder `po/` within each individual LuCI component directory, e.g. `applications/luci-app-acl/po/`.
-You find the reference in `po/templates/<package>.pot`.
+The template is in `po/templates/<package>.pot`.
 The actual translation files can be found at `po/[lang]/[package].po`.
 
 In order to use the commands below you need to have the `gettext` utilities (`msgcat`, `msgfmt`, `msgmerge`) installed on your system.
-On Debian/Ubuntu you can install with `sudo apt install gettext`.
+On Debian/Ubuntu, install them with `sudo apt install gettext`.
 
 ### Initialize po files
 
-When you add or update an app, simply run from your app folder:
+When you add or update an app, run from your `applications/luci-app-acl/` app folder:
 
     ../../build/i18n-add-language.sh
 
-This creates the skeleton po files for all existing languages open for translation for your app.
+This creates the skeleton .po files for all available languages open for translation for your app.
 
 Or from the luci repo root:
 
     ./build/i18n-add-language.sh
 
-This creates the skeleton po files for all existing languages open for translation for all sub-folders.
+This creates the skeleton .po files for all existing languages open for translation for all sub-folders.
 
-### Rebuild po files
-If you want to rebuild the translations after you made changes to a package this is an easy way:
+### Rebuild po files (for existing languages)
+After you make changes to a package, run:
 
-    ./build/i18n-scan.pl applications/[application] > applications/[application]/po/templates/[application_basename].pot
-    ./build/i18n-update.pl applications/[application]/po
+    ./build/i18n-sync.sh applications/[application]
 
 Example:
 
-    ./build/i18n-scan.pl applications/luci-app-acl > applications/luci-app-acl/po/templates/acl.pot
-    ./build/i18n-update.pl applications/luci-app-acl/po
+    ./build/i18n-sync.sh applications/luci-app-acl
 
-Note that the directory argument can be omitted for `i18n-update.pl` to update all apps.
+This only updates those language .po files that already exist in `applications/luci-app-acl/po/`. See the previous step to add a new language.
 
-Some packages share translation files, in this case you need to scan through all their folders.
-The first command from above should then be:
+Note: the directory argument can be omitted to update all po template and po files.
+
+
+Some packages share translation files, in this case you need to scan through all their folders:
 
     ./build/i18n-scan.pl applications/[package-1] applications/[package-2] applications/[package-n] > [location of shared template]/[application].pot
 
-*Note:* The translation catalog for the base system covers multiple components, use the following commands to update it:
+This is what the `mkbasepot.sh` script does for the `luci-base` module:
+
+    ./build/i18n-scan.pl \
+        modules/luci-base modules/luci-compat modules/luci-lua-runtime \
+        modules/luci-mod-network modules/luci-mod-status modules/luci-mod-system \
+        protocols themes \
+    > modules/luci-base/po/templates/base.pot
+
+*Note:* The translation catalog for the base system covers multiple components. Use the following commands to update it:
 
     ./build/mkbasepot.sh
     ./build/i18n-update.pl
 
 ### LMO files
 The `*.po` files are big so Luci needs them in a compact compiled [LMO format](./LMO.md).
-Luci reads `*.lmo` translations from `/usr/lib/lua/luci/i18n/` folder.
+Luci reads `*.lmo` translations from the `/usr/lib/lua/luci/i18n/` folder.
 E.g. `luci-app-acl` has an Arabic translation in `luci-i18n-acl-ar` package that installs `/usr/lib/lua/luci/i18n/acl.ar.lmo` file.
 
 In order to quickly convert a single `.po` file to `.lmo` file for testing on the target system use the `po2lmo` utility.
@@ -109,9 +117,9 @@ You will need to compile it from the `luci-base` module:
      $ ./po2lmo
      Usage: ./po2lmo input.po output.lmo
 
-Now you can compile and upload translation:
+Now you can compile and upload the translation:
 
      ./po2lmo ../../../applications/luci-app-acl/po/ar/acl.po ./acl.ar.lmo
      scp ./acl.ar.lmo root@192.168.1.1:/usr/lib/lua/luci/i18n/
 
-You can change language in [System /Language and Style](http://192.168.1.1/cgi-bin/luci/admin/system/system) and check the translation.
\ No newline at end of file
+You can change languages in [System /Language and Style](http://192.168.1.1/cgi-bin/luci/admin/system/system) and check the translation.