Introduce Glossary Messages #62

stasm · 2017-10-31T16:59:48Z

Goal

Recognize the glossary translations type which cannot be retrieved by the calling code.

Summary

The proposed syntax for glossary messages is via an identifier starting with - (a dash):

-brand-name = Firefox
app-title = { -brand-name }

Glossary messages cannot be retrieved from the MessageContext they're defined in and they can only be referenced in other messages. Glossary messages and public messages are separate AST nodes extending the message node in the ASDL spec.

Description

Glossary translations are not intended to be used directly by the calling code. Instead they should go through another, public, message. The current syntax already hints at this by disallowing tags and attributes to be defined on the same message. The introduction of glossary messages will make this design explicit.

-brand-name = Firefox
application-title = { -brand-name }

This change boils down to allowing - as the first character of the identifier. Its consequences are, however, far-reaching. Tools like compare-locales should not inspect attributes of glossary messages. These attributes are consequently private and cannot be used for translating widget attributes (like in HTML). They may be used for language-specific information and they could replace tags.

Example

English:

-brand-name = Firefox

app-title = { -brand-name }
has-updated = { -brand-name } has been updated.

Polish (with glossary attributes replacing tags):

-brand-name =
    {
       *[nominative] Firefox
        [genitive] Firefoksa
    }
    .gender = masculine

app-title = { -brand-name }
has-updated =
    { -brand-name.gender ->
        [masculine] { -brand-name } został zaktualizowany.
        [feminine] { -brand-name } została zaktualizowana.
       *[other] Program { -brand-name } został zaktualizowany.
    }

Private Messages

By allowing - as the first character of the identifier we will also enable ids of the form --foo. These could be used by tools to differentiate between glossary messages which must be present in an FTL file and private messages which are localizer-defined.

--tab = tab
open-tab = Open a new { --tab }

I would still encourage everyone to spell the whole sentence out:

open-tab = Open a new tab

Signoffs

The text was updated successfully, but these errors were encountered:

flodolo · 2017-10-31T17:11:30Z

Can you clarify what problem this would solve? I'm wondering if I'm missing a good technical reason to support this.

What would happen if the code calls directly -brand-name?

stasm · 2017-10-31T17:55:52Z

Can you clarify what problem this would solve? I'm wondering if I'm missing a good technical reason to support this.

There are two big reasons:

Codify the logical split that already exists because tags and attributes cannot co-exist on a single message. The syntax would clearly communicate where tags are allowed (-foo) and where attributes are allowed (foo).
Or, we could allow attributes on glossary messages. compare-locales would treat them as private and we could use them as we use tags right now. In effect we could remove tags and make the syntax simpler.

What would happen if the code calls directly -brand-name?

MessageContext would throw an error.

Pike · 2017-11-01T18:36:46Z

The bit here that is interesting to me is private messages, which we have only in the sense of obsolete messages right now.
A glossary message is kind of a suggested-private message, vs private-private messages?

I wonder if syntax is the right abstraction level for this. Wouldn't this make implementing parsers quite a bit harder? Also, what'd be the value of a private message?

I'm not a big fan of going back from tags to key-value pairs, I think I like the concept of not having to name things twice by now.

stasm · 2017-11-02T13:09:09Z

A glossary message is kind of a suggested-private message, vs private-private messages?

Yes :) The first draft of this issue used private and double-private as names for these abstractions. Note that the distinction would only be enforced and understood by tools. Fluent would only recognize public vs. private. All ids with a leading - are private for Fluent; this includes both -foo and --foo.

For tools like compare-locales, -foo would mean must exists (but don't check tags) and --foo would mean can exist if en-US doesn't have it.

I wonder if syntax is the right abstraction level for this. Wouldn't this make implementing parsers quite a bit harder? Also, what'd be the value of a private message?

We already have an artifact of this thinking in the syntax:

fluent/spec/fluent.ebnf

Line 44 in 3c0e901

    
           message              ::= identifier ((value tag-list?) | (value? attribute-list))

Introducing an explicit AST production for this would actually make it easier to enforce this in parsers and serializers.

I'm not a big fan of going back from tags to key-value pairs, I think I like the concept of not having to name things twice by now.

I'm still thinking about this. I like it too but I also see a lot of value in having one type of data fewer. I'll file another issue about this and let's keep this one about private / glossary messages.

zbraniecki · 2017-11-03T01:03:37Z

Need to think about it a bit more, but several thoughts after reading it twice:

I like the reuse of attributes for tags. I understand the "not having to name it twice" value for the author, but I place the value for the reader to understand a concept above it. I findgender = masculine more explicit #masculine and that's a win in my book.
I'm slightly worried about "-" as the sign to denote glossary messages because it will definitely, forever, remove the ability to use math operators on IDs. I don't know where and if we will ever use it, but it feels to me that we could easily use a different sign (_ or --) and avoid that trap, even if we don't see any need for math operators now.
I'm not sure if I understand the value of separating glossary items from private messages yet. Maybe I need more time to think about it or more help to understand it.

stasm · 2017-11-03T08:48:33Z

I'm slightly worried about "-" as the sign to denote glossary messages because it will definitely, forever, remove the ability to use math operators on IDs.

We already allow dashes inside of identifiers which has the same problem. I really doubt we'll ever need to subtract two ids. If we do, there are always s-expressions :)

I'm not sure if I understand the value of separating glossary items from private messages yet. Maybe I need more time to think about it or more help to understand it.

This distinction would only be made by tools. For Fluent, -foo and --foo are simply two private messages with ids of the form - followed by a string of chars. None of them can be retrieved from their MessageContext.

The double dash is the proposed convention for tools to differentiate between messages that should be present in the localization if the reference has them (-foo) and those that may exist in the localization if the reference doesn't have them (--foo). Consider the following example:

-brand-name = Firefox
app-title = { -brand-name }

A tool like compare-locales can verify that the localization contains the -brand-name message as well as that the app-title message references -brand-name. Any messages starting with -- would be ignored in compare-locales stats and checks.

Fix projectfluent#62. Private messages are similar to regular messages but they can only be used as references in other messages. The runtime cannot retrieve them directly. They are best used to define glossary terms which can be used consistently across the localization of the entire product. Private messages can store some grammatical information about themselves in tags. Private messages are not allowed to have attributes.

Fix projectfluent#62. Private messages are similar to regular messages but they can only be used as references in other messages. Their identifiers start with at least one dash `-`, e.g. `-brand-name`. The runtime cannot retrieve private messages directly. They are best used to define glossary terms which can be used consistently across the localization of the entire product. Private messages can store some grammatical information about themselves in tags. Private messages are not allowed to have attributes.

stasm · 2017-11-23T15:44:05Z

Before we discuss the implementation in #68, I'd like to get sign-offs on this proposal from the majority of the core team. Please comment in this thread and tick the box next to your name if you give this proposal a green light.

stasm · 2017-11-23T15:44:40Z

r+

zbraniecki · 2017-11-24T02:35:06Z

r+

Fix projectfluent#62. Private messages are similar to regular messages but they can only be used as references in other messages. Their identifiers start with at least one dash `-`, e.g. `-brand-name`. The runtime cannot retrieve private messages directly. They are best used to define glossary terms which can be used consistently across the localization of the entire product. Private messages can store some grammatical information about themselves in tags. Private messages are not allowed to have attributes.

stasm · 2018-01-30T07:38:03Z

In #85 I suggested renaming private messages to terms. This was implemented in #86.

stasm added this to the Syntax 0.4 milestone Nov 2, 2017

stasm modified the milestones: Syntax 0.4, Syntax 0.5 Nov 8, 2017

stasm mentioned this issue Nov 10, 2017

Remove tags #67

Closed

3 tasks

stasm added the syntax label Nov 10, 2017

stasm mentioned this issue Nov 14, 2017

Introduce private messages. #68

Merged

stasm closed this as completed in #68 Nov 30, 2017

stasm mentioned this issue Dec 4, 2017

Require = after the identifier #63

Closed

3 tasks

This was referenced Jan 23, 2018

Add private messages projectfluent/fluent.js#130

Merged

Maybe rename private messages? #85

Closed

Pike mentioned this issue May 25, 2018

Specify and allow Private Terms #130

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Introduce Glossary Messages #62

Introduce Glossary Messages #62

stasm commented Oct 31, 2017 •

edited by Pike

Loading

flodolo commented Oct 31, 2017

stasm commented Oct 31, 2017

Pike commented Nov 1, 2017

stasm commented Nov 2, 2017

zbraniecki commented Nov 3, 2017 •

edited

Loading

stasm commented Nov 3, 2017 •

edited

Loading

stasm commented Nov 23, 2017 •

edited by Pike

Loading

stasm commented Nov 23, 2017

zbraniecki commented Nov 24, 2017

stasm commented Jan 30, 2018

Introduce Glossary Messages #62

Introduce Glossary Messages #62

Comments

stasm commented Oct 31, 2017 • edited by Pike Loading

Goal

Summary

Description

Example

Private Messages

Signoffs

flodolo commented Oct 31, 2017

stasm commented Oct 31, 2017

Pike commented Nov 1, 2017

stasm commented Nov 2, 2017

zbraniecki commented Nov 3, 2017 • edited Loading

stasm commented Nov 3, 2017 • edited Loading

stasm commented Nov 23, 2017 • edited by Pike Loading

stasm commented Nov 23, 2017

zbraniecki commented Nov 24, 2017

stasm commented Jan 30, 2018

stasm commented Oct 31, 2017 •

edited by Pike

Loading

zbraniecki commented Nov 3, 2017 •

edited

Loading

stasm commented Nov 3, 2017 •

edited

Loading

stasm commented Nov 23, 2017 •

edited by Pike

Loading