pipeline

Documentation

Overview

Package pipeline provides tools for creating translation pipelines.

NOTE: UNDER DEVELOPMENT. API MAY CHANGE.

Index

• func Generate(w io.Writer, pkg string, extracted *Messages, trans ...Messages) (n int, err error)
• func Rewrite(w io.Writer, args ...string) error
• type Config
• type Feature
• type IDList
  • func (id *IDList) MarshalJSON() ([]byte, error)
  • func (id *IDList) UnmarshalJSON(b []byte) error
• type Message
  • func (m *Message) Placeholder(id string) *Placeholder
  • func (m *Message) Substitute(msg string) (sub string, err error)
• type Messages
• type Placeholder
• type Select
• type State
  • func Extract(c *Config) (*State, error)
  • func (s *State) Export() error
  • func (s *State) Generate() error
  • func (s *State) Import() error
  • func (s *State) Merge() error
  • func (s *State) WriteGen(w io.Writer, pkg string) error
• type Text
  • func (t *Text) IsEmpty() bool
  • func (t *Text) MarshalJSON() ([]byte, error)
  • func (t *Text) UnmarshalJSON(b []byte) error

Functions

func Generate

func Generate(w io.Writer, pkg string, extracted *Messages, trans ...Messages) (n int, err error)

Generate is deprecated; use (*State).Generate().

func Rewrite

func Rewrite(w io.Writer, args ...string) error

Rewrite rewrites the Go files in a single package to use the localization machinery and rewrites strings to adopt best practices when possible. If w is not nil the generated files are written to it, each files with a "--- <filename>" header. Otherwise the files are overwritten.

Types

type Config

type Config struct {
	// Supported indicates the languages for which data should be generated.
	// The default is to support all locales for which there are matching
	// translation files.
	Supported []language.Tag

	SourceLanguage language.Tag

	Packages []string

	// Dir is the root dir for all operations.
	Dir string

	// TranslationsPattern is a regular expression to match incoming translation
	// files. These files may appear in any directory rooted at Dir.
	// language for the translation files is determined as follows:
	//   1. From the Language field in the file.
	//   2. If not present, from a valid language tag in the filename, separated
	//      by dots (e.g. "en-US.json" or "incoming.pt_PT.xmb").
	//   3. If not present, from a the closest subdirectory in which the file
	//      is contained that parses as a valid language tag.
	TranslationsPattern string

	// OutPattern defines the location for translation files for a certain
	// language. The default is "{{.Dir}}/{{.Language}}/out.{{.Ext}}"
	OutPattern string

	// Format defines the file format for generated translation files.
	// The default is XMB. Alternatives are GetText, XLIFF, L20n, GoText.
	Format string

	Ext string

	// GenFile may be in a different package. It is not defined, it will
	// be written to stdout.
	GenFile string

	// GenPackage is the package or relative path into which to generate the
	// file. If not specified it is relative to the current directory.
	GenPackage string

	// DeclareVar defines a variable to which to assign the generated Catalog.
	DeclareVar string

	// SetDefault determines whether to assign the generated Catalog to
	// message.DefaultCatalog. The default for this is true if DeclareVar is
	// not defined, false otherwise.
	SetDefault bool
}

Config contains configuration for the translation pipeline.

type Feature

type Feature struct {
	Type string `json:"type"` // Right now this is only gender and plural.

}

Feature holds information about a feature that can be implemented by an Argument.

type IDList

type IDList []string

IDList is a set identifiers that each may refer to possibly different versions of the same message. When looking up a messages, the first identifier in the list takes precedence.

func (*IDList) MarshalJSON

func (id *IDList) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*IDList) UnmarshalJSON

func (id *IDList) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.

type Message

type Message struct {
	// ID contains a list of identifiers for the message.
	ID IDList `json:"id"`
	// Key is the string that is used to look up the message at runtime.
	Key         string `json:"key,omitempty"`
	Meaning     string `json:"meaning,omitempty"`
	Message     Text   `json:"message"`
	Translation Text   `json:"translation"`

	Comment           string `json:"comment,omitempty"`
	TranslatorComment string `json:"translatorComment,omitempty"`

	Placeholders []Placeholder `json:"placeholders,omitempty"`

	// Fuzzy indicates that the provide translation needs review by a
	// translator, for instance because it was derived from automated
	// translation.
	Fuzzy bool `json:"fuzzy,omitempty"`

	// Extraction information.
	Position string `json:"position,omitempty"` // filePosition:line
}

A Message describes a message to be translated.

func (*Message) Placeholder

func (m *Message) Placeholder(id string) *Placeholder

Placeholder reports the placeholder for the given ID if it is defined or nil otherwise.

func (*Message) Substitute

func (m *Message) Substitute(msg string) (sub string, err error)

Substitute replaces placeholders in msg with their original value.

type Messages

type Messages struct {
	Language language.Tag    `json:"language"`
	Messages []Message       `json:"messages"`
	Macros   map[string]Text `json:"macros,omitempty"`
}

Messages is used to store translations for a single language.

type Placeholder

type Placeholder struct {
	// ID is the placeholder identifier without the curly braces.
	ID string `json:"id"`

	// String is the string with which to replace the placeholder. This may be a
	// formatting string (for instance "%d" or "{{.Count}}") or a literal string
	// (<div>).
	String string `json:"string"`

	Type           string `json:"type"`
	UnderlyingType string `json:"underlyingType"`
	// ArgNum and Expr are set if the placeholder is a substitution of an
	// argument.
	ArgNum int    `json:"argNum,omitempty"`
	Expr   string `json:"expr,omitempty"`

	Comment string `json:"comment,omitempty"`
	Example string `json:"example,omitempty"`

	// Features contains the features that are available for the implementation
	// of this argument.
	Features []Feature `json:"features,omitempty"`
}

A Placeholder is a part of the message that should not be changed by a translator. It can be used to hide or prettify format strings (e.g. %d or {{.Count}}), hide HTML, or mark common names that should not be translated.

type Select

type Select struct {
	Feature string          `json:"feature"` // Name of Feature type (e.g plural)
	Arg     string          `json:"arg"`     // The placeholder ID
	Cases   map[string]Text `json:"cases"`
}

Select selects a Text based on the feature value associated with a feature of a certain argument.

type State

type State struct {
	Config Config

	Package string

	Extracted Messages `json:"messages"`

	// Messages includes all messages for which there need to be translations.
	// Duplicates may be eliminated. Generation will be done from these messages
	// (usually after merging).
	Messages []Messages

	// Translations are incoming translations for the application messages.
	Translations []Messages
	// contains filtered or unexported fields
}

State holds all accumulated information on translations during processing.

func Extract

func Extract(c *Config) (*State, error)

Extract extracts all strings form the package defined in Config.

func (*State) Export

func (s *State) Export() error

Export writes out the messages to translation out files.

func (*State) Generate

func (s *State) Generate() error

Generate writes a Go file that defines a Catalog with translated messages. Translations are retrieved from s.Messages, not s.Translations, so it is assumed Merge has been called.

func (*State) Import

func (s *State) Import() error

Import loads existing translation files.

func (*State) Merge

func (s *State) Merge() error

Merge merges the extracted messages with the existing translations.

func (*State) WriteGen

func (s *State) WriteGen(w io.Writer, pkg string) error

WriteGen writes a Go file with the given package name to w that defines a Catalog with translated messages. Translations are retrieved from s.Messages, not s.Translations, so it is assumed Merge has been called.

type Text

type Text struct {
	// Msg and Select contains the message to be displayed. Msg may be used as
	// a fallback value if none of the select cases match.
	Msg    string  `json:"msg,omitempty"`
	Select *Select `json:"select,omitempty"`

	// Var defines a map of variables that may be substituted in the selected
	// message.
	Var map[string]Text `json:"var,omitempty"`

	// Example contains an example message formatted with default values.
	Example string `json:"example,omitempty"`
}

Text defines a message to be displayed.

func (*Text) IsEmpty

func (t *Text) IsEmpty() bool

IsEmpty reports whether this Text can generate anything.

func (*Text) MarshalJSON

func (t *Text) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*Text) UnmarshalJSON

func (t *Text) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.