Rename private messages to terms

Fixes projectfluent#85

guide/SUMMARY.md

@@ -7,7 +7,7 @@
 * [Selectors](selectors.md)
 * [Variants](variants.md)
 * [Attributes](attributes.md)
-* [Private Messages](private.md)
+* [Terms](terms.md)
 * [Comments](comments.md)
 * [Built-in Functions](builtins.md)
 * [Functions](functions.md)

guide/attributes.md

@@ -23,7 +23,7 @@ This feature is particularly useful in translating more complex widgets since,
 thanks to all attributes being stored on a single unit, it's easier for editors,
 comments, and tools to identify and work with the given message.
 
-Attributes may also be used to define grammatical properties of [private
-messages](private.html). Attributes of private messages are also private and
-may not be retrieved by the localization runtime. They can only be used as
+Attributes may also be used to define grammatical properties of
+[terms](terms.html). Attributes of terms are private and may not be retrieved
+by the localization runtime. They can only be used as
 [selectors](selectors.html).

guide/references.md

@@ -13,14 +13,14 @@ consistent across the interface and makes maintenance easier.
 It is also particularly handy for keeping branding separated from the rest of
 the translations, so that it can be changed easily when needed, e.g. during
 the build process of the application. This use-case is best served by
-defining a [private message](private.html) with a leading dash `-`, like
-`-brand-name` in the example below.
+defining a [term](terms.html) with a leading dash `-`, like `-brand-name` in
+the example below.
 
 ```
 -brand-name = Firefox
 installing = Installing { -brand-name }.
 ```
 
-The use of the private message indicates to tools and to the localization
-runtime that `-brand-name` is not supposed to be used directly in the product
-but rather should be referenced in other messages.
+Using a term here indicates to tools and to the localization runtime that
+`-brand-name` is not supposed to be used directly in the product but rather
+should be referenced in other messages.

guide/terms.md

@@ -0,0 +1,60 @@
+# Terms
+
+Terms are similar to regular messages but they can only be used as references
+in other messages. Their identifiers start with a single dash `-` like in the
+example above: `-brand-name`. The runtime cannot retrieve terms directly.
+They are best used to define vocabulary and glossary items which can be used
+consistently across the localization of the entire product.
+
+```
+-brand-name = Firefox
+
+app-title = { -brand-name }
+has-updated = { -brand-name } has been updated.
+```
+
+## Terms and Variants
+
+Values of terms may have multiple [variants](variants.html), including the
+default variant marked with an asterisk (`*`). For instance, variants may
+correspond to different grammatical cases.
+
+```
+-brand-name =
+    {
+       *[nominative] Firefox
+        [accusative] Firefoxa
+    }
+
+app-title = { -brand-name }
+restart-app = Zrestartuj { -brand-name[accusative] }.
+```
+
+Use variants to define different _facets_ of the term's value. Variants
+are essentially the same value, just in slightly different forms to make it
+grammatically correct when used inside of other messages.
+
+## Terms and Attributes
+
+Sometimes other translations might vary depending on some grammatical trait
+of a term references in them. Terms can store this grammatical information
+about themselves in [attributes](attributes.html). In the example below the
+form of the past tense of _has been updated_ depends on the grammatical
+gender of `-brand-name`.
+
+```
+-brand-name = Aurora
+    .gender = feminine
+
+has-updated =
+    { -brand-name.gender ->
+        [masculine] { -brand-name} został zaktualizowany.
+        [feminine] { -brand-name } została zaktualizowana.
+       *[other] Program { -brand-name } został zaktualizowany.
+    }
+```
+
+Use attributes to describe grammatical traits and properties. Genders,
+animacy, whether the term essage starts with a vowel or not etc. Attributes
+of terms are private and may not be retrieved by the localization runtime.
+They can only be used as [selectors](selectors.html).

spec/CHANGELOG.md

@@ -2,17 +2,17 @@
 
 ## Unreleased
 
-  - Added private messages. (#62)
+  - Added terms. (#62, #85)
 
-    Private messages start their identifiers with a single dash `-`.
+    Terms are entries which can only be referenced by other messages. Terms
+    cannot be retrieved by the `MessageContext` runtime.
 
-    Private messages cannot be retrieved by the `MessageContext` runtime.
-    Tools may introduce different checks for private and public messages.
+    Terms start their identifiers with a single dash `-`. Tools may introduce
+    different checks for messages and terms.
 
   - Removed tags. (#67)
 
-    The same functionality can be achieved by using attributes defined on
-    private messages.
+    The same functionality can be achieved by using term attributes.
 
     ```properties
     -brand-name = Firefox
@@ -56,7 +56,7 @@
   - The dash `-` is not allowed at the beginning of identifiers.
 
     There's an ongoing discussion in #62 about using the leading `-` for
-    private messages in the future.
+    private messages (terms) in the future.
 
   - The question mark `?` is not allowed in identifiers.
 

spec/fluent.asdl

@@ -26,11 +26,13 @@ module Fluent
     res = Resource(entry* body, span? span)
 
     entry = Message(message)
+          | Term(term)
           | Comment(comment)
           | Junk(str content)
           attributes (annot* annotations, span? span)
 
     message = Message(iden id, pat? value, attr* attributes, comment? comment)
+    term = Term(iden id, pat value, attr* attributes, comment? comment)
 
     annot = Annotation(str code, str* args, str message, span? span)
     span = Span(int start, int end)
@@ -52,7 +54,7 @@ module Fluent
            | Placeable(expr expression)
            attributes (span? span)
 
-    -- Attributes of Message
+    -- Attributes of Messages and Terms
     attr = Attribute(iden id, pat value, span? span)
 
     -- Variants of SelectExpression

spec/fluent.ebnf

@@ -1,7 +1,7 @@
 body                 ::= blank-line* (entry line-break blank-line*)* entry? EOF
-entry                ::= comment
-                       | section
-                       | message
+entry                ::= message
+                       | term
+                       | comment
 
 comment              ::= ('#' (inline-space (char - line-break)*)? line-break)+
                        | ('##' (inline-space (char - line-break)*)? line-break)+
@@ -23,7 +23,7 @@ _                    ::= inline-space
 __                   ::= break-indent
 
 identifier           ::= [a-zA-Z] [a-zA-Z0-9_-]*
-private-identifier   ::= '-' identifier
+term-identifier      ::= '-' identifier
 external-identifier  ::= '$' identifier
 
 /* exclude whitespace and [ \ ] { } */
@@ -39,7 +39,7 @@ variant-list         ::= variant* default-variant variant* line-break
 attribute            ::= __ '.' identifier value
 
 message              ::= identifier (value attribute* | attribute+)
-                       | private-identifier value attribute*
+term                 ::= term-identifier value attribute*
 
 value                ::= _? '=' __? pattern
 pattern              ::= (text | placeable)+
@@ -58,9 +58,9 @@ inline-expression    ::= quoted-text
                        | number
                        | external-identifier
                        | identifier
-                       | public-attribute-expression
-                       | private-identifier
-                       | private-variant-expression
+                       | message-attribute-expression
+                       | term-identifier
+                       | term-variant-expression
                        | call-expression
                        | placeable
 block-expression     ::= select-expression
@@ -70,12 +70,12 @@ select-expression    ::= selector-expression __ '->' __ variant-list
 selector-expression  ::= quoted-text
                        | number
                        | external-identifier
-                       | private-attribute-expression
+                       | term-attribute-expression
                        | call-expression
 
-public-attribute-expression  ::= identifier '.' identifier
-private-attribute-expression ::= private-identifier '.' identifier
-private-variant-expression   ::= private-identifier '[' _? variant-key _? ']'
+message-attribute-expression  ::= identifier '.' identifier
+term-attribute-expression     ::= term-identifier '.' identifier
+term-variant-expression       ::= term-identifier '[' _? variant-key _? ']'
 
 call-expression      ::= builtin '(' __? argument-list? __? ')'
 argument-list        ::= argument ( __? ',' __? argument)* __? ','?