vendor/golang.org/x/text/message/doc.go

   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
   5 // Package message implements formatted I/O for localized strings with functions
   6 // analogous to the fmt's print functions. It is a drop-in replacement for fmt.
   7 //
   8 //
   9 // Localized Formatting
  10 //
  11 // A format string can be localized by replacing any of the print functions of
  12 // fmt with an equivalent call to a Printer.
  13 //
  14 //    p := message.NewPrinter(language.English)
  15 //    p.Println(123456.78) // Prints 123,456.78
  16 //
  17 //    p := message.NewPrinter(language.Bengali)
  18 //    p.Println(123456.78) // Prints ১,২৩,৪৫৬.৭৮
  19 //
  20 // Printer currently supports numbers and specialized types for which packages
  21 // exist in x/text. Other builtin types such as time.Time and slices are
  22 // planned.
  23 //
  24 // Format strings largely have the same meaning as with fmt with the following
  25 // notable exceptions:
  26 //   - flag # always resorts to fmt for printing
  27 //   - verb 'f', 'e', 'g', 'd' use localized formatting unless the '#' flag is
  28 //     specified.
  29 //
  30 // See package fmt for more options.
  31 //
  32 //
  33 // Translation
  34 //
  35 // The format strings that are passed to Printf, Sprintf, Fprintf, or Errorf
  36 // are used as keys to look up translations for the specified languages.
  37 // More on how these need to be specified below.
  38 //
  39 // One can use arbitrary keys to distinguish between otherwise ambiguous
  40 // strings:
  41 //    p := message.NewPrinter(language.English)
  42 //    p.Printf("archive(noun)")  // Prints "archive"
  43 //    p.Printf("archive(verb)")  // Prints "archive"
  44 //
  45 //    p := message.NewPrinter(language.German)
  46 //    p.Printf("archive(noun)")  // Prints "Archiv"
  47 //    p.Printf("archive(verb)")  // Prints "archivieren"
  48 //
  49 // To retain the fallback functionality, use Key:
  50 //    p.Printf(message.Key("archive(noun)", "archive"))
  51 //    p.Printf(message.Key("archive(verb)", "archive"))
  52 //
  53 //
  54 // Translation Pipeline
  55 //
  56 // Format strings that contain text need to be translated to support different
  57 // locales. The first step is to extract strings that need to be translated.
  58 //
  59 // 1. Install gotext
  60 //    go get -u golang.org/x/text/cmd/gotext
  61 //    gotext -help
  62 //
  63 // 2. Mark strings in your source to be translated by using message.Printer,
  64 // instead of the functions of the fmt package.
  65 //
  66 // 3. Extract the strings from your source
  67 //
  68 //    gotext extract
  69 //
  70 // The output will be written to the textdata directory.
  71 //
  72 // 4. Send the files for translation
  73 //
  74 // It is planned to support multiple formats, but for now one will have to
  75 // rewrite the JSON output to the desired format.
  76 //
  77 // 5. Inject translations into program
  78 //
  79 // 6. Repeat from 2
  80 //
  81 // Right now this has to be done programmatically with calls to Set or
  82 // SetString. These functions as well as the methods defined in
  83 // see also package golang.org/x/text/message/catalog can be used to implement
  84 // either dynamic or static loading of messages.
  85 //
  86 //
  87 // Plural and Gender Forms
  88 //
  89 // Translated messages can vary based on the plural and gender forms of
  90 // substitution values. In general, it is up to the translators to provide
  91 // alternative translations for such forms. See the packages in
  92 // golang.org/x/text/feature and golang.org/x/text/message/catalog for more
  93 // information.
  94 //
  95 package message