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