From 0bd3249fefe8614d23ab7c1e128f78f420bf11a5 Mon Sep 17 00:00:00 2001
From: Cory Francis Myers <cory@freedom.press>
Date: Thu, 5 Oct 2023 18:20:04 -0700
Subject: [PATCH] docs: subsection "Localization" section for clarity

---
 Makefile | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index a38cd89df1..1af5851aa2 100644
--- a/Makefile
+++ b/Makefile
@@ -340,17 +340,22 @@ upgrade-destroy:  ## Destroy an upgrade test environment.
 #
 ##############
 
+# Global configuration:
 I18N_CONF=securedrop/i18n.json
 I18N_LIST=securedrop/i18n.rst
 
+# securedrop/securedrop configuration:
 LOCALE_DIR=securedrop/translations
-POT=${LOCALE_DIR}/messages.pot
+POT=$(LOCALE_DIR)/messages.pot
 
+# securedrop/desktop configuration:
 DESKTOP_BASE=install_files/ansible-base/roles/tails-config/templates
 DESKTOP_LOCALE_DIR=$(DESKTOP_BASE)/locale
 DESKTOP_I18N_CONF=$(DESKTOP_LOCALE_DIR)/LINGUAS
 DESKTOP_POT=$(DESKTOP_LOCALE_DIR)/messages.pot
 
+## Global
+
 .PHONY: check-strings
 check-strings: $(POT) $(DESKTOP_POT) ## Check that the translation catalogs are up to date with source code.
 	@$(MAKE) --no-print-directory extract-strings
@@ -360,6 +365,8 @@ check-strings: $(POT) $(DESKTOP_POT) ## Check that the translation catalogs are
 extract-strings: $(POT) $(DESKTOP_POT) ## Extract translatable strings from source code.
 	@$(MAKE) --always-make --no-print-directory $^
 
+## securedrop/securedrop
+
 # Derive POT from sources.
 $(POT): securedrop
 	@echo "updating catalog template: $@"
@@ -380,6 +387,8 @@ $(POT): securedrop
 		$^
 	@sed -i -e '/^"POT-Creation-Date/d' $@
 
+## securedrop/desktop
+
 .PHONY: check-desktop-files
 check-desktop-files: ${DESKTOP_BASE}/*.j2
 	@$(MAKE) --always-make --no-print-directory update-desktop-files
@@ -420,6 +429,8 @@ $(DESKTOP_POT): ${DESKTOP_BASE}/*.in
 $(DESKTOP_I18N_CONF):
 	@jq --raw-output '.supported_locales[].desktop' ${I18N_CONF} > $@
 
+## Supported locales
+
 .PHONY: check-supported-locales
 check-supported-locales: $(I18N_LIST) $(DESKTOP_I18N_CONF) ## Check that the desktop and documentation lists of supported locales are up to date.
 	@$(MAKE) --no-print-directory update-supported-locales
@@ -444,6 +455,8 @@ ${I18N_LIST}: ${I18N_CONF}
 supported-locales: ## List supported locales (languages).
 	@jq --compact-output '.supported_locales | keys' ${I18N_CONF}
 
+## Utilities
+
 .PHONY: translation-test
 translation-test: ## Run page layout tests in all supported languages.
 	@echo "Running translation tests..."