diff --git a/README.md b/README.md
index c494151..d5aa379 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,32 @@
 
 Welcome to our new site, built on Docusaurus. This integrates our previous simple jekyll site and our documentation work from Gitbook into a single site. It also provides a blog capability, and built-in capability for localization.
 
-## Localization Mapping from the butter-app-site
+## Localization
+
+All localizations (currently en, es, ru and zh-Hans) are under the www/i18n/ folder structure
+
+Key files for localization are:
+
+- homepage and general strings: www/i18n/<locale>/code.json
+- navbar: www/i18n/<locale>/docusaurus-theme-classic/navbar.json 
+- footer: www/i18n/<locale>/docusaurus-theme-classic/footer.json 
+- english markdown docs: www/docs/
+- localization markdown docs: www/i18n/<locale>/docusaurus-plugin-content-docs/current/
+
+### Locale commands
+
+To update translation key values:
+ npm run write-translations -- --locale <locale>
+
+To run the site in a specific locale:
+ npm run start -- --locale <locale> 
+
+To build the static site for all locales:
+ npm run build
+
+### Localization mapping
+
+Below is a rough mapping from the old jekyll site i18n strings file fields into the new www/i18n/en/code.json file, for the main page.
 
 - home.subtitle2 = from the top-level title
 - home.whatisbutterbox = butter_box.device_image_caption