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