feat: define the postcode field and its message catalogue

CONTEXT.md

@@ -169,6 +169,14 @@ _Avoid_: input, widget, picker
 To show the user what a postcode points to before the app stores it.
 _Avoid_: verify, validate (for this step)
 
+**Form value**:
+The text that a field gives its form when the form is sent: the canonical form of a postcode, the 6 digits of a legacy postcode, or the text without white space at the start and the end.
+_Avoid_: submitted value, output
+
+**Message catalogue**:
+A data file that holds the text of a UI in one language, one message for each key.
+_Avoid_: strings file, translations, locale file
+
 **Tell**:
 A habit that makes code look machine-written, such as very long lines.
 _Avoid_: smell (smells are design problems), anti-pattern

README.md

@@ -69,6 +69,8 @@ Every SDK runs the cases in [`vectors/`](vectors).
 |---|---|
 | [`grammar.md`](grammar.md) | how every SDK reads and writes postcodes, and the public interface |
 | [`client.md`](client.md) | how every client calls NIPOST's gateway: results, errors, retries and the queue |
+| [`field.md`](field.md) | how every postcode field behaves: settings, events, states, accessibility and privacy |
+| [`messages/`](messages) | the text of the field, one message catalogue for each language |
 | [`openapi/`](openapi) | NIPOST's gateway, completed with the responses that its own file leaves out |
 | [`fixtures/`](fixtures) | synthetic gateway responses and keys for the mock server |
 | [`contract/`](contract) | shared client test cases that every client must pass against the mock server |

REUSE.toml

@@ -1,7 +1,9 @@
 version = 1
 
 [[annotations]]
-path = ["**/*.md", "**/*.json", "**/*.yml", "VERSION", "NOTICE", "templates/NOTICE"]
+path = [
+  "**/*.md", "**/*.json", "**/*.yml", "messages/*.arb", "VERSION", "NOTICE", "templates/NOTICE",
+]
 precedence = "aggregate"
 SPDX-FileCopyrightText = "2026 The Gatepost authors"
 SPDX-License-Identifier = "Apache-2.0"

VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

grammar.md

@@ -1,6 +1,6 @@
 # Postcode grammar
 
-Spec version 0.2.0. This file defines how every Gatepost SDK reads and writes Nigeria's digital postcodes. The values live in `data/`. The vectors in `vectors/` test every rule, except the rules in the list below. If this file and a vector disagree, this file wins. Such a disagreement is a bug in the spec.
+Spec version 0.3.0. This file defines how every Gatepost SDK reads and writes Nigeria's digital postcodes. The values live in `data/`. The vectors in `vectors/` test every rule, except the rules in the list below. If this file and a vector disagree, this file wins. Such a disagreement is a bug in the spec.
 
 No shared vector tests these rules. Each SDK tests them itself.
 

messages/field_en.arb

@@ -0,0 +1,138 @@
+{
+  "@@locale": "en",
+  "label": "Postcode",
+  "@label": {
+    "description": "The label of the input, when the page gives no label."
+  },
+  "hint": "11 letters and numbers, for example EK 01 A03 FK 01",
+  "@hint": {
+    "description": "The hint under the label. The example is the one in NIPOST's docs."
+  },
+  "empty": "Enter your postcode.",
+  "@empty": {
+    "description": "The input is required and empty."
+  },
+  "bad_character": "Use only letters and numbers.",
+  "@bad_character": {
+    "description": "The text holds a character that a postcode never has, such as a comma."
+  },
+  "bad_length": "A postcode has 11 letters and numbers. You entered {count}.",
+  "@bad_length": {
+    "description": "The text has too few or too many characters. Spaces and hyphens do not count.",
+    "placeholders": {
+      "count": {
+        "type": "int"
+      }
+    }
+  },
+  "unknown_state": "The first part must be a state code, such as LA or FC.",
+  "@unknown_state": {
+    "description": "The first 2 letters are not one of the 37 state codes."
+  },
+  "bad_lga": "The second part must be a number from 01 to 99.",
+  "@bad_lga": {
+    "description": "The LGA segment, the second part, is not a number from 01 to 99."
+  },
+  "bad_area": "The fourth part must be 2 letters.",
+  "@bad_area": {
+    "description": "The area segment, the fourth part, holds a digit."
+  },
+  "bad_unit": "The last part must be a number from 01 to 99.",
+  "@bad_unit": {
+    "description": "The unit segment, the last part, is not a number from 01 to 99."
+  },
+  "suggestion": "Did you mean {postcode}?",
+  "@suggestion": {
+    "description": "A fix of look-alike characters, such as O for 0, gives this postcode.",
+    "placeholders": {
+      "postcode": {
+        "type": "String"
+      }
+    }
+  },
+  "use_suggestion": "Use this postcode",
+  "@use_suggestion": {
+    "description": "The button that puts the suggested postcode in the input."
+  },
+  "legacy_accepted": "This is an old 6-digit postcode. If you know your new one, enter it instead.",
+  "@legacy_accepted": {
+    "description": "The text is an old postcode, and the page accepts old postcodes."
+  },
+  "legacy_rejected": "This is an old 6-digit postcode. Enter a new one, such as EK 01 A03 FK 01.",
+  "@legacy_rejected": {
+    "description": "The text is an old postcode, and the page needs a new one."
+  },
+  "valid": "This postcode is in {state}.",
+  "@valid": {
+    "description": "The postcode has the right format. No check with NIPOST ran.",
+    "placeholders": {
+      "state": {
+        "type": "String"
+      }
+    }
+  },
+  "checking": "Checking your postcode.",
+  "@checking": {
+    "description": "The field is asking NIPOST about the postcode."
+  },
+  "not_found": "We could not find this postcode. Check each part, or continue if you are sure.",
+  "@not_found": {
+    "description": "NIPOST does not know the postcode. The user can still send the form."
+  },
+  "confirmed": "We found this postcode in {state}.",
+  "@confirmed": {
+    "description": "NIPOST knows the postcode.",
+    "placeholders": {
+      "state": {
+        "type": "String"
+      }
+    }
+  },
+  "confirmed_place": "We found this postcode: {locality}, {lga}, {state}.",
+  "@confirmed_place": {
+    "description": "NIPOST knows the postcode and gave the names of its place.",
+    "placeholders": {
+      "locality": {
+        "type": "String"
+      },
+      "lga": {
+        "type": "String"
+      },
+      "state": {
+        "type": "String"
+      }
+    }
+  },
+  "check_failed": "We could not check this postcode just now. You can still continue.",
+  "@check_failed": {
+    "description": "The request to NIPOST failed, for example with no network."
+  },
+  "secret_key": "We cannot check postcodes on this page. You can still continue.",
+  "@secret_key": {
+    "description": "The page holds a secret key, so the field sends no request."
+  },
+  "use_location": "Use my location",
+  "@use_location": {
+    "description": "The button that finds the postcode of the user's location."
+  },
+  "locating": "Finding your location.",
+  "@locating": {
+    "description": "The field waits for the location, or for NIPOST's answer about it."
+  },
+  "gps_coarse": "We added part of your postcode from your location. Type the rest.",
+  "@gps_coarse": {
+    "description": "The location gave only part of a postcode, which the field put in the input."
+  },
+  "gps_not_found": "We found no postcode at your location. Type your postcode.",
+  "@gps_not_found": {
+    "description": "NIPOST has no postcode near the location."
+  },
+  "gps_denied": "We cannot use your location. Type your postcode.",
+  "@gps_denied": {
+    "description": "The user or the platform refused the location."
+  },
+  "gps_unavailable": "We could not find your location. Type your postcode.",
+  "@gps_unavailable": {
+    "description": "The device gave no location, or the request to NIPOST failed."
+  }
+}