src/third_party/libaddressinput/src/cpp/include/libaddressinput/localization.h

   1 // Copyright (C) 2013 Google Inc.
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6 //
   7 // http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14
  15 #ifndef I18N_ADDRESSINPUT_LOCALIZATION_H_
  16 #define I18N_ADDRESSINPUT_LOCALIZATION_H_
  17
  18 #include <libaddressinput/address_field.h>
  19 #include <libaddressinput/address_problem.h>
  20 #include <libaddressinput/util/basictypes.h>
  21
  22 #include <string>
  23
  24 namespace i18n {
  25 namespace addressinput {
  26
  27 struct AddressData;
  28
  29 // The object to retrieve localized strings based on message IDs. It returns
  30 // English by default. Sample usage:
  31 //    Localization localization;
  32 //    std::string best_language_tag;
  33 //    Process(BuildComponents("CA", localization, "en-US", &best_language_tag));
  34 //
  35 // Alternative usage:
  36 //    Localization localization;
  37 //    localization.SetGetter(&MyStringGetter);
  38 //    std::string best_language_tag;
  39 //    Process(BuildComponents("CA", localization, "fr-CA", &best_language_tag));
  40 class Localization {
  41  public:
  42   // Initializes with English messages by default.
  43   Localization();
  44   ~Localization();
  45
  46   // Returns the localized string for |message_id|. Returns an empty string if
  47   // there's no message with this identifier.
  48   std::string GetString(int message_id) const;
  49
  50   // Returns the error message. If |enable_examples| is false, then the error
  51   // message will not contain examples of valid input. If |enable_links| is
  52   // false, then the error message will not contain HTML links. (Some error
  53   // messages contain postal code examples or link to post office websites to
  54   // look up the postal code for an address). Vector field values (e.g. for
  55   // street address) should not be empty if problem is UNKNOWN_VALUE. The
  56   // POSTAL_CODE field should only be used with MISSING_REQUIRED_FIELD,
  57   // INVALID_FORMAT, and MISMATCHING_VALUE problem codes. All other fields
  58   // should only be used with MISSING_REQUIRED_FIELD, UNKNOWN_VALUE, and
  59   // USES_P_O_BOX problem codes.
  60   std::string GetErrorMessage(const AddressData& address,
  61                               AddressField field,
  62                               AddressProblem problem,
  63                               bool enable_examples,
  64                               bool enable_links) const;
  65
  66   // Sets the string getter that takes a message identifier and returns the
  67   // corresponding localized string. For example, in Chromium there is
  68   // l10n_util::GetStringUTF8 which always returns strings in the current
  69   // application locale.
  70   void SetGetter(std::string (*getter)(int));
  71
  72  private:
  73   // Returns the error message where the address field is a postal code. Helper
  74   // to |GetErrorMessage|. If |postal_code_example| is empty, then the error
  75   // message will not contain examples of valid postal codes. If
  76   // |post_service_url| is empty, then the error message will not contain a post
  77   // service URL. The problem should only be one of MISSING_REQUIRED_FIELD,
  78   // INVALID_FORMAT, or MISMATCHING_VALUE.
  79   std::string GetErrorMessageForPostalCode(const AddressData& address,
  80                                            AddressProblem problem,
  81                                            bool uses_postal_code_as_label,
  82                                            std::string postal_code_example,
  83                                            std::string post_service_url) const;
  84
  85   // The string getter.
  86   std::string (*get_string_)(int);
  87
  88   DISALLOW_COPY_AND_ASSIGN(Localization);
  89 };
  90
  91 }  // namespace addressinput
  92 }  // namespace i18n
  93
  94 #endif  // I18N_ADDRESSINPUT_LOCALIZATION_H_