extensions/common/message_bundle.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef EXTENSIONS_COMMON_MESSAGE_BUNDLE_H_
   6 #define EXTENSIONS_COMMON_MESSAGE_BUNDLE_H_
   7
   8 #include <map>
   9 #include <string>
  10 #include <vector>
  11
  12 #include "base/memory/linked_ptr.h"
  13
  14 namespace base {
  15 class DictionaryValue;
  16 class Value;
  17 }
  18
  19 namespace extensions {
  20
  21 // Contains localized extension messages for one locale. Any messages that the
  22 // locale does not provide are pulled from the default locale.
  23 class MessageBundle {
  24  public:
  25   typedef std::map<std::string, std::string> SubstitutionMap;
  26   typedef std::vector<linked_ptr<base::DictionaryValue> > CatalogVector;
  27
  28   // JSON keys of interest for messages file.
  29   static const char* kContentKey;
  30   static const char* kMessageKey;
  31   static const char* kPlaceholdersKey;
  32
  33   // Begin/end markers for placeholders and messages
  34   static const char* kPlaceholderBegin;
  35   static const char* kPlaceholderEnd;
  36   static const char* kMessageBegin;
  37   static const char* kMessageEnd;
  38
  39   // Reserved message names in the dictionary.
  40   // Update i18n documentation when adding new reserved value.
  41   static const char* kUILocaleKey;
  42   // See http://code.google.com/apis/gadgets/docs/i18n.html#BIDI for
  43   // description.
  44   // TODO(cira): point to chrome docs once they are out.
  45   static const char* kBidiDirectionKey;
  46   static const char* kBidiReversedDirectionKey;
  47   static const char* kBidiStartEdgeKey;
  48   static const char* kBidiEndEdgeKey;
  49   // Extension id gets added in the
  50   // browser/renderer_host/resource_message_filter.cc to enable message
  51   // replacement for non-localized extensions.
  52   static const char* kExtensionIdKey;
  53
  54   // Values for some of the reserved messages.
  55   static const char* kBidiLeftEdgeValue;
  56   static const char* kBidiRightEdgeValue;
  57
  58   // Creates MessageBundle or returns NULL if there was an error. Expects
  59   // locale_catalogs to be sorted from more specific to less specific, with
  60   // default catalog at the end.
  61   static MessageBundle* Create(const CatalogVector& locale_catalogs,
  62                                std::string* error);
  63
  64   // Get message from the catalog with given key.
  65   // Returned message has all of the internal placeholders resolved to their
  66   // value (content).
  67   // Returns empty string if it can't find a message.
  68   // We don't use simple GetMessage name, since there is a global
  69   // #define GetMessage GetMessageW override in Chrome code.
  70   std::string GetL10nMessage(const std::string& name) const;
  71
  72   // Get message from the given catalog with given key.
  73   static std::string GetL10nMessage(const std::string& name,
  74                                     const SubstitutionMap& dictionary);
  75
  76   // Number of messages in the catalog.
  77   // Used for unittesting only.
  78   size_t size() const { return dictionary_.size(); }
  79
  80   // Replaces all __MSG_message__ with values from the catalog.
  81   // Returns false if there is a message in text that's not defined in the
  82   // dictionary.
  83   bool ReplaceMessages(std::string* text, std::string* error) const;
  84   // Static version that accepts dictionary.
  85   static bool ReplaceMessagesWithExternalDictionary(
  86       const SubstitutionMap& dictionary, std::string* text, std::string* error);
  87
  88   // Replaces each occurance of variable placeholder with its value.
  89   // I.e. replaces __MSG_name__ with value from the catalog with the key "name".
  90   // Returns false if for a valid message/placeholder name there is no matching
  91   // replacement.
  92   // Public for easier unittesting.
  93   static bool ReplaceVariables(const SubstitutionMap& variables,
  94                                const std::string& var_begin,
  95                                const std::string& var_end,
  96                                std::string* message,
  97                                std::string* error);
  98
  99   // Allow only ascii 0-9, a-z, A-Z, and _ in the variable name.
 100   // Returns false if the input is empty or if it has illegal characters.
 101   static bool IsValidName(const std::string& name);
 102
 103   // Getter for dictionary_.
 104   const SubstitutionMap* dictionary() const { return &dictionary_; }
 105
 106   ~MessageBundle();
 107
 108  private:
 109   // Testing friend.
 110   friend class MessageBundleTest;
 111
 112   // Use Create to create MessageBundle instance.
 113   MessageBundle();
 114
 115   // Initializes the instance from the contents of vector of catalogs.
 116   // If the key is not present in more specific catalog we fall back to next one
 117   // (less specific).
 118   // Returns false on error.
 119   bool Init(const CatalogVector& locale_catalogs, std::string* error);
 120
 121   // Appends locale specific reserved messages to the dictionary.
 122   // Returns false if there was a conflict with user defined messages.
 123   bool AppendReservedMessagesForLocale(const std::string& application_locale,
 124                                        std::string* error);
 125
 126   // Helper methods that navigate JSON tree and return simplified message.
 127   // They replace all $PLACEHOLDERS$ with their value, and return just key/value
 128   // of the message.
 129   bool GetMessageValue(const std::string& key,
 130                        const base::Value& name_value,
 131                        std::string* value,
 132                        std::string* error) const;
 133
 134   // Get all placeholders for a given message from JSON subtree.
 135   bool GetPlaceholders(const base::DictionaryValue& name_tree,
 136                        const std::string& name_key,
 137                        SubstitutionMap* placeholders,
 138                        std::string* error) const;
 139
 140   // For a given message, replaces all placeholders with their actual value.
 141   // Returns false if replacement failed (see ReplaceVariables).
 142   bool ReplacePlaceholders(const SubstitutionMap& placeholders,
 143                            std::string* message,
 144                            std::string* error) const;
 145
 146   // Holds all messages for application locale.
 147   SubstitutionMap dictionary_;
 148 };
 149
 150 ///////////////////////////////////////////////////////////////////////////////
 151 //
 152 // Renderer helper typedefs and functions.
 153 //
 154 ///////////////////////////////////////////////////////////////////////////////
 155
 156 // A map of message name to message.
 157 typedef std::map<std::string, std::string> L10nMessagesMap;
 158
 159 // A map of extension ID to l10n message map.
 160 typedef std::map<std::string, L10nMessagesMap > ExtensionToL10nMessagesMap;
 161
 162 // Returns the extension_id to messages map.
 163 ExtensionToL10nMessagesMap* GetExtensionToL10nMessagesMap();
 164
 165 // Returns message map that matches given extension_id, or NULL.
 166 L10nMessagesMap* GetL10nMessagesMap(const std::string& extension_id);
 167
 168 // Erases the L10nMessagesMap for the given |extension_id|.
 169 void EraseL10nMessagesMap(const std::string& extension_id);
 170
 171 }  // namespace extensions
 172
 173 #endif  // EXTENSIONS_COMMON_MESSAGE_BUNDLE_H_