Issue 5068 - Define translation string format

translation-string-format.md

 # Websites translation string format
 
 ## Format
 
-`{{ $uid[$tag-name $tag-attribute] $contents }}`
+`{{ $uid[$context] $contents }}`
+
+### $uid (required)
+
+Format
+:   >= 1 alphanumeric asic char
+
+Exceptions
+:   Should be human readable if reused.
+
+### $context (optional - unnesisary for reuse)
+
+Format
+:   Parent HTML tag and attribute name (if applicable)
+
+Exceptions
+:   - Expand tag names e.g. "p" -> "paragraph"
+    - Exclude irrelivant information like heading number e.g. "h1" -> "heading"
+    - Provide functional context if applicable  e.g. "title" -> "tooltip"
+
+### $content (optional - unnessisary for reuse)
+
+Format:
+:   >= 1 UTF-8 char
+
+Exceptions:
+:   Should not contain "}}"
 
 ## Example
 
 ```
-<section>
-  <h1>{{ 1[heading text] Example heading }}</h1>
-  <p>{{ 2[paragraph text] Example paragraph }}</p>
-  <ul>
-    <li>{{ 5[list item text] List item }}</li>
-  </ul>
-  <a title="{{ 3[link tooltip text] Example tooltip }}">{{ 4[link text] Example link }}</a>
-</section>
+<nav>
+  <h1>{{ brand-name[heading] Adblock Plus }}</h1>
+  ...
+</nav>
+<header>
+  <h1>{{ brand-name }}</h1>
+  <p>{{ 1[subtitle] Blocks annoying ads }}</p>
+</header>
+...
 ```
 
-## Explination
+- Notice how "brand-name" is reused
+- Notice how "1" has functional context
+- Notice that "1" is a UID not an NID. It could just as easily be "a" or "9" as long as it's not used more than once on the page.
 
-### $uid
+## FAQ
 
-A numeric unique identifier.
+Why not make all string IDs human readable?
+:  Because picky humans cannot generate or review them efficiently
 
-### $tag-name
-
-A human readable tag name.
-
-### $tag-attribute
-
-A human readable tag attribute name.
-
-### $contents
-
-String contents.
-
-### FAQ
-
-Should $uid be human readable?
-:   No, because making it human readable only complicates things.
-
-Should $tag-name be human readable?
-:   Yes, use common sense to expand abbreviations e.g. p -> paragraph and exclude irrelivant information like heading number.
-
-Should $attribute-name be human readable?
-:   Yes, use common sense to expand the meaning of the attribute e.g. title -> tooltip.
-
-What if there is no attribute?
-:   Use "text".
-
-What about naming conflicts?
-:   These should be easy to spot if we test/preview and review changes. These could also be identified by linting.
+Why not add location information to string contexts?
+:  Because [picky humans cannot generate or review them efficiently, we often begin translation before implementation, we don't have a staging system to show visual context information].