1// Copyright 2017 The Go Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style
3// license that can be found in the LICENSE file.
4
5package pipeline
6
7import (
8	"encoding/json"
9	"strings"
10
11	"golang.org/x/text/language"
12)
13
14// TODO: these definitions should be moved to a package so that the can be used
15// by other tools.
16
17// The file contains the structures used to define translations of a certain
18// messages.
19//
20// A translation may have multiple translations strings, or messages, depending
21// on the feature values of the various arguments. For instance, consider
22// a hypothetical translation from English to English, where the source defines
23// the format string "%d file(s) remaining".
24// See the examples directory for examples of extracted messages.
25
26// Config contains configuration for the translation pipeline.
27type Config struct {
28	SourceLanguage language.Tag
29
30	// Supported indicates the languages for which data should be generated.
31	// If unspecified, it will attempt to derive the set of supported languages
32	// from the context.
33	Supported []language.Tag
34
35	Packages []string
36
37	// TODO:
38	// - Printf-style configuration
39	// - Template-style configuration
40	// - Extraction options
41	// - Rewrite options
42	// - Generation options
43}
44
45// A Locale is used to store all information for a single locale. This type is
46// used both for extraction and injection.
47type Locale struct {
48	Language language.Tag    `json:"language"`
49	Messages []Message       `json:"messages"`
50	Macros   map[string]Text `json:"macros,omitempty"`
51}
52
53// A Message describes a message to be translated.
54type Message struct {
55	// ID contains a list of identifiers for the message.
56	ID IDList `json:"id"`
57	// Key is the string that is used to look up the message at runtime.
58	Key         string `json:"key"`
59	Meaning     string `json:"meaning,omitempty"`
60	Message     Text   `json:"message"`
61	Translation Text   `json:"translation"`
62
63	Comment           string `json:"comment,omitempty"`
64	TranslatorComment string `json:"translatorComment,omitempty"`
65
66	Placeholders []Placeholder `json:"placeholders,omitempty"`
67
68	// TODO: default placeholder syntax is {foo}. Allow alternative escaping
69	// like `foo`.
70
71	// Extraction information.
72	Position string `json:"position,omitempty"` // filePosition:line
73}
74
75// Placeholder reports the placeholder for the given ID if it is defined or nil
76// otherwise.
77func (m *Message) Placeholder(id string) *Placeholder {
78	for _, p := range m.Placeholders {
79		if p.ID == id {
80			return &p
81		}
82	}
83	return nil
84}
85
86// Substitute replaces placeholders in msg with their original value.
87func (m *Message) Substitute(msg string) (sub string, err error) {
88	last := 0
89	for i := 0; i < len(msg); {
90		pLeft := strings.IndexByte(msg[i:], '{')
91		if pLeft == -1 {
92			break
93		}
94		pLeft += i
95		pRight := strings.IndexByte(msg[pLeft:], '}')
96		if pRight == -1 {
97			return "", errorf("unmatched '}'")
98		}
99		pRight += pLeft
100		id := strings.TrimSpace(msg[pLeft+1 : pRight])
101		i = pRight + 1
102		if id != "" && id[0] == '$' {
103			continue
104		}
105		sub += msg[last:pLeft]
106		last = i
107		ph := m.Placeholder(id)
108		if ph == nil {
109			return "", errorf("unknown placeholder %q in message %q", id, msg)
110		}
111		sub += ph.String
112	}
113	sub += msg[last:]
114	return sub, err
115}
116
117// A Placeholder is a part of the message that should not be changed by a
118// translator. It can be used to hide or prettify format strings (e.g. %d or
119// {{.Count}}), hide HTML, or mark common names that should not be translated.
120type Placeholder struct {
121	// ID is the placeholder identifier without the curly braces.
122	ID string `json:"id"`
123
124	// String is the string with which to replace the placeholder. This may be a
125	// formatting string (for instance "%d" or "{{.Count}}") or a literal string
126	// (<div>).
127	String string `json:"string"`
128
129	Type           string `json:"type"`
130	UnderlyingType string `json:"underlyingType"`
131	// ArgNum and Expr are set if the placeholder is a substitution of an
132	// argument.
133	ArgNum int    `json:"argNum,omitempty"`
134	Expr   string `json:"expr,omitempty"`
135
136	Comment string `json:"comment,omitempty"`
137	Example string `json:"example,omitempty"`
138
139	// Features contains the features that are available for the implementation
140	// of this argument.
141	Features []Feature `json:"features,omitempty"`
142}
143
144// An argument contains information about the arguments passed to a message.
145type argument struct {
146	// ArgNum corresponds to the number that should be used for explicit argument indexes (e.g.
147	// "%[1]d").
148	ArgNum int `json:"argNum,omitempty"`
149
150	used           bool   // Used by Placeholder
151	Type           string `json:"type"`
152	UnderlyingType string `json:"underlyingType"`
153	Expr           string `json:"expr"`
154	Value          string `json:"value,omitempty"`
155	Comment        string `json:"comment,omitempty"`
156	Position       string `json:"position,omitempty"`
157}
158
159// Feature holds information about a feature that can be implemented by
160// an Argument.
161type Feature struct {
162	Type string `json:"type"` // Right now this is only gender and plural.
163
164	// TODO: possible values and examples for the language under consideration.
165
166}
167
168// Text defines a message to be displayed.
169type Text struct {
170	// Msg and Select contains the message to be displayed. Msg may be used as
171	// a fallback value if none of the select cases match.
172	Msg    string  `json:"msg,omitempty"`
173	Select *Select `json:"select,omitempty"`
174
175	// Var defines a map of variables that may be substituted in the selected
176	// message.
177	Var map[string]Text `json:"var,omitempty"`
178
179	// Example contains an example message formatted with default values.
180	Example string `json:"example,omitempty"`
181}
182
183// IsEmpty reports whether this Text can generate anything.
184func (t *Text) IsEmpty() bool {
185	return t.Msg == "" && t.Select == nil && t.Var == nil
186}
187
188// rawText erases the UnmarshalJSON method.
189type rawText Text
190
191// UnmarshalJSON implements json.Unmarshaler.
192func (t *Text) UnmarshalJSON(b []byte) error {
193	if b[0] == '"' {
194		return json.Unmarshal(b, &t.Msg)
195	}
196	return json.Unmarshal(b, (*rawText)(t))
197}
198
199// MarshalJSON implements json.Marshaler.
200func (t *Text) MarshalJSON() ([]byte, error) {
201	if t.Select == nil && t.Var == nil && t.Example == "" {
202		return json.Marshal(t.Msg)
203	}
204	return json.Marshal((*rawText)(t))
205}
206
207// IDList is a set identifiers that each may refer to possibly different
208// versions of the same message. When looking up a messages, the first
209// identifier in the list takes precedence.
210type IDList []string
211
212// UnmarshalJSON implements json.Unmarshaler.
213func (id *IDList) UnmarshalJSON(b []byte) error {
214	if b[0] == '"' {
215		*id = []string{""}
216		return json.Unmarshal(b, &((*id)[0]))
217	}
218	return json.Unmarshal(b, (*[]string)(id))
219}
220
221// MarshalJSON implements json.Marshaler.
222func (id *IDList) MarshalJSON() ([]byte, error) {
223	if len(*id) == 1 {
224		return json.Marshal((*id)[0])
225	}
226	return json.Marshal((*[]string)(id))
227}
228
229// Select selects a Text based on the feature value associated with a feature of
230// a certain argument.
231type Select struct {
232	Feature string          `json:"feature"` // Name of Feature type (e.g plural)
233	Arg     string          `json:"arg"`     // The placeholder ID
234	Cases   map[string]Text `json:"cases"`
235}
236
237// TODO: order matters, but can we derive the ordering from the case keys?
238// type Case struct {
239// 	Key   string `json:"key"`
240// 	Value Text   `json:"value"`
241// }
242