diff --git a/docs/abra/hack.md b/docs/abra/hack.md
index 8564aa7..a22a0da 100644
--- a/docs/abra/hack.md
+++ b/docs/abra/hack.md
@@ -220,6 +220,49 @@ bats -Tp tests/integration --filter-status failed # re-run only failed
 
 If you're running into issues and want to debug stuff, you can pass `-x` to `bats` to trace all commands run in the test. You can add `echo '...' >&3` debug statements to your test to output stuff also.
 
+## Internationalisation
+
+`abra` can be translated into other languages. We use a combination of [`gettext`](https://www.gnu.org/software/gettext/), [`weblate`](https://translate.coopcloud.tech) and some intermediate automation to help developers and translatorsto work together in a convenient workflow.
+
+### Developer workflow
+
+You just hack on `abra` as you normally would. If you need to add a string, use `i18n.G` to wrap it. See [`gotext`](https://github.com/leonelquinteros/gotext) for the full API.
+
+For example.
+
+```go
+i18n.G("my string")
+i18n.G("my string with err: %s", err)
+log.Debug(i18n.G("my string"))
+```
+
+Then you need to update the `pkg/i18n/locales/abra.pot` file with your new strings for the translators.
+
+```bash
+apt install -y gettext
+go install -v -x github.com/snapcore/snapd/i18n/xgettext-go@2.57.1
+make i18n
+```
+
+Commit the changes. Ignore `*.mo` changes if they only update the generation timestamp.
+
+### Translator workflow
+
+You can translate strings on [`translate.coopcloud.tech`](https://translate.coopcloud.tech).
+
+It's also possible to translate using [`poedit`](https://poedit.net).
+
+Once translations are updated, they will be incorporated into the next release of `abra` automatically.
+
+### End-user workflow
+
+You simply export the `LANG` env var to match your desired translation.
+
+```
+export LANG=es
+abra -h
+```
+
 ## Using the `abra` public API
 
 Warning, there is currently no stability promise for the `abra` public API! Most of the internals are exposed in order to allow a free hand for developers to try build stuff. If people start to build things then we can start the discussion on what is useful to have open/closed and keep stable etc. Please let us know if you depend on the APIs!