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
14namespace base {
15class DictionaryValue;
16class Value;
17}
18
19namespace 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.
23class 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.
157typedef std::map<std::string, std::string> L10nMessagesMap;
158
159// A map of extension ID to l10n message map.
160typedef std::map<std::string, L10nMessagesMap > ExtensionToL10nMessagesMap;
161
162// Returns the extension_id to messages map.
163ExtensionToL10nMessagesMap* GetExtensionToL10nMessagesMap();
164
165// Returns message map that matches given extension_id, or NULL.
166L10nMessagesMap* GetL10nMessagesMap(const std::string& extension_id);
167
168// Erases the L10nMessagesMap for the given |extension_id|.
169void EraseL10nMessagesMap(const std::string& extension_id);
170
171}  // namespace extensions
172
173#endif  // EXTENSIONS_COMMON_MESSAGE_BUNDLE_H_
174