Mercurial > repos > IBBoard
annotate Lang/Translation.cs @ 6:f269d8bcc152
Re #2 - Refactor API
* Refactor translations in to smaller and clearer functions
* Add "get current translation language" function
* Add documentation of public methods
| author | IBBoard <dev@ibboard.co.uk> |
|---|---|
| date | Sat, 27 Dec 2008 20:28:04 +0000 |
| parents | f9ec2be467fe |
| children | f4da31cb09d9 |
| rev | line source |
|---|---|
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
1 using System; |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
2 using System.IO; |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
3 using System.Xml; |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
4 using System.Xml.Schema; |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
5 using System.Collections.Generic; |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
6 using System.Reflection; |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
7 using System.ComponentModel; |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
8 using IBBoard.IO; |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
9 using IBBoard.Logging; |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
10 using IBBoard.Xml; |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
11 |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
12 namespace IBBoard.Lang |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
13 { |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
14 /// <summary> |
| 6 | 15 /// A basic string translator that loads a default language and a specified language and returns translated strings that correspond to translation IDs. |
| 16 /// If the string doesn't exist in the specified language then the translator falls back to the default language. If the translation doesn't exist in the default language | |
| 17 /// then either a supplied value or a "no validation available" message is returned. | |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
18 /// </summary> |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
19 public class Translation |
| 6 | 20 { |
| 21 private static readonly string DEFAULT_LANGUAGE = "en"; | |
| 22 private static readonly string DIVIDER_STRING = "-"; | |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
23 private static string lang = ""; |
| 6 | 24 private static DirectoryInfo translationDir; |
| 25 private static Dictionary<string, string> translationsLocal; | |
| 26 private static Dictionary<string, string> translationsDefault; | |
| 27 | |
| 28 /// <summary> | |
| 29 /// Initialises the translations for the language specified and the default translations so that the Translation class can be used | |
| 30 /// </summary> | |
| 31 /// <param name="appPath"> | |
| 32 /// The full path that the application is running from. Must contain the "translations" folder. | |
| 33 /// </param> | |
| 34 /// <param name="language"> | |
| 35 /// The language to use as the load language | |
| 36 /// </param> | |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
37 public static void InitialiseTranslations(string appPath, string language) |
| 6 | 38 { |
| 39 InitialiseDefaults(appPath); | |
| 40 FileInfo file = GetTranslationFile(DEFAULT_LANGUAGE); | |
| 41 XmlDocument doc = LoadTranslationDocument(file); | |
| 42 LoadTranslationsFromDocument(doc, translationsDefault); | |
| 43 translationsLocal = null; | |
| 44 LoadTranslation(lang); | |
| 45 } | |
| 46 | |
| 47 private static void InitialiseDefaults(string appPath) | |
| 48 { | |
| 49 string translationPath = appPath.TrimEnd(Constants.DirectoryChar) + Constants.DirectoryString + "translations"; | |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
50 |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
51 if (Directory.Exists(translationPath)) |
| 6 | 52 { |
| 53 translationsDefault = new Dictionary<string,string>(); | |
| 54 translationsLocal = new Dictionary<string,string>(); | |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
55 translationDir = new DirectoryInfo(translationPath); |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
56 } |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
57 else |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
58 { |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
59 throw new ArgumentException("Translation path must exist ("+translationPath+")"); |
| 6 | 60 } |
| 61 } | |
| 62 | |
| 63 private static XmlDocument LoadTranslationDocument(FileInfo file) | |
| 64 { | |
| 65 XmlDocument doc = new XmlDocument(); | |
| 66 XmlReaderSettings settings = new XmlReaderSettings(); | |
| 67 settings.XmlResolver = new IBBXmlResolver(translationDir.Parent.FullName); | |
| 68 settings.ValidationType = ValidationType.DTD; | |
| 69 settings.ProhibitDtd = false; | |
| 70 settings.ValidationEventHandler+= new ValidationEventHandler(ValidationEventMethod); | |
| 71 XmlReader valReader = XmlReader.Create(file.FullName, settings); | |
| 72 doc.Load(valReader); | |
| 73 valReader.Close(); | |
| 74 return doc; | |
| 75 } | |
| 76 | |
| 77 private static FileInfo GetTranslationFile(string language) | |
| 78 { | |
| 79 FileInfo file = new FileInfo(translationDir.FullName + Constants.DirectoryString + language + ".translation"); | |
| 80 | |
| 81 if (!file.Exists) | |
| 82 { | |
| 83 throw new FileNotFoundException(language + "translation could not be found in "+translationDir.FullName); | |
| 84 } | |
| 85 | |
| 86 return file; | |
| 87 } | |
| 88 | |
| 89 private static void LoadTranslationsFromDocument(XmlDocument doc, Dictionary<string, string> translationTable) | |
| 90 { | |
| 91 try | |
| 92 { | |
| 93 XmlNodeList translations = doc.GetElementsByTagName("translation"); | |
| 94 | |
| 95 if (translations.Count==0) | |
| 96 { | |
| 97 throw new InvalidFileException("No translations found in "+GetLanguageOfDocument(doc)+".translation"); | |
| 98 } | |
| 99 | |
| 100 Dictionary<string, string> tempTranslationTable = new Dictionary<string,string>(); | |
| 101 | |
| 102 foreach (XmlNode node in translations) | |
| 103 { | |
| 104 tempTranslationTable.Add(node.Attributes["id"].Value, node.InnerText); | |
| 105 } | |
| 106 | |
| 107 translationTable.Clear(); | |
| 108 | |
| 109 foreach (string key in tempTranslationTable.Keys) | |
| 110 { | |
| 111 string translation; | |
| 112 tempTranslationTable.TryGetValue(key, out translation); | |
| 113 translationTable.Add(key, translation); | |
| 114 } | |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
115 } |
| 6 | 116 catch(Exception ex) |
| 117 { | |
| 118 throw new XmlParseException("Error while parsing " + GetLanguageOfDocument(doc)+" translation: "+ex.Message); | |
| 119 } | |
| 120 } | |
| 121 | |
| 122 private static string GetLanguageOfDocument(XmlDocument doc) | |
| 123 { | |
| 124 return doc != null ? doc.DocumentElement.GetAttribute("lang") : ""; | |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
125 } |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
126 |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
127 private static void ValidationEventMethod(object sender, ValidationEventArgs e) |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
128 { |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
129 //TODO: Fire a validation failure event |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
130 LogNotifier.Error(typeof(Translation), "Validation Error", e.Exception); |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
131 } |
| 6 | 132 |
| 133 /// <summary> | |
| 134 /// Loads translations for a given language and sets them as the local language | |
| 135 /// </summary> | |
| 136 /// <param name="translationLang"> | |
| 137 /// The new local language to load | |
| 138 /// </param> | |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
139 public static void LoadTranslation(string translationLang) |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
140 { |
| 6 | 141 checkInitialisation(); |
| 142 | |
| 143 if (translationLang == "" || translationLang == null) | |
| 144 { | |
| 145 throw new ArgumentException("Translation language cannot be empty or null"); | |
| 146 } | |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
147 |
| 6 | 148 if (translationLang != DEFAULT_LANGUAGE) |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
149 { |
| 6 | 150 FileInfo file = GetTranslationFile(translationLang); |
| 151 XmlDocument doc = LoadTranslationDocument(file); | |
| 152 LoadTranslationsFromDocument(doc, translationsLocal); | |
| 153 } | |
| 154 else | |
| 155 { | |
| 156 translationsLocal.Clear(); | |
| 157 } | |
| 158 | |
| 159 lang = translationLang; | |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
160 } |
| 6 | 161 |
| 162 /// <summary> | |
| 163 /// Gets a translation for a given ID, falling back to a "missing translation" message if none can be found. Also optionally replaces any placeholders with the supplied values. | |
| 164 /// </summary> | |
| 165 /// <param name="translationID"> | |
| 166 /// The ID to look up the translation for | |
| 167 /// </param> | |
| 168 /// <param name="replacements"> | |
| 169 /// A collection of <see cref="System.Object"/>s to replace placeholders with | |
| 170 /// </param> | |
| 171 /// <returns> | |
| 172 /// The translation with the placeholders replaced or a "missing translation" message | |
| 173 /// </returns> | |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
174 public static string GetTranslation(string translationID, params object[] replacements) |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
175 { |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
176 return GetTranslation(translationID, false, replacements); |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
177 } |
| 6 | 178 |
| 179 /// <summary> | |
| 180 /// Gets a translation for a given ID, falling back to null or a warning message if a translation cannot be found. Also optionally replaces any placeholders with the supplied values. | |
| 181 /// </summary> | |
| 182 /// <param name="translationID"> | |
| 183 /// The ID to look up the translation for | |
| 184 /// </param> | |
| 185 /// <param name="returnNullOnFail"> | |
| 186 /// TRUE if null should be returned when no translation can be found, or FALSE if a "missing translation" message should be returned | |
| 187 /// </param> | |
| 188 /// <param name="replacements"> | |
| 189 /// A collection of <see cref="System.Object"/>s to replace placeholders with | |
| 190 /// </param> | |
| 191 /// <returns> | |
| 192 /// The translation with the placeholders replaced, or a "missing translation" message or null depending on <param name="returnNullOnFail"> | |
| 193 /// </returns> | |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
194 public static string GetTranslation(string translationID, bool returnNullOnFail, params object[] replacements) |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
195 { |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
196 return GetTranslation(translationID, returnNullOnFail ? null : "", replacements); |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
197 } |
| 6 | 198 |
| 199 /// <summary> | |
| 200 /// Gets a translation for a given ID, falling back to a supplied default if a translation cannot be found. Also optionally replaces any placeholders with the supplied values. | |
| 201 /// </summary> | |
| 202 /// <param name="translationID"> | |
| 203 /// The ID to look up the translation for | |
| 204 /// </param> | |
| 205 /// <param name="defaultTranslation"> | |
| 206 /// The string to return if no translation can be found. Can be null or any string. | |
| 207 /// </param> | |
| 208 /// <param name="replacements"> | |
| 209 /// A collection of <see cref="System.Object"/>s to replace placeholders with | |
| 210 /// </param> | |
| 211 /// <returns> | |
| 212 /// The translation, if one exists, or the supplied default with the placeholders replaced | |
| 213 /// </returns> | |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
214 public static string GetTranslation(string translationID, string defaultTranslation, params object[] replacements) |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
215 { |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
216 checkInitialisation(); |
| 6 | 217 string trans = GetTranslationFromTables(translationID); |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
218 |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
219 if (trans == null) |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
220 { |
| 6 | 221 trans = GetDefaultTranslation(translationID, defaultTranslation); |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
222 } |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
223 |
| 6 | 224 trans = AddVariablesToTranslation(trans, replacements); |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
225 |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
226 return trans; |
| 6 | 227 } |
| 228 | |
| 229 private static string GetTranslationFromTables(string translationID) | |
| 230 { | |
| 231 string translation = null; | |
| 232 | |
| 233 if (translationsLocal!=null) | |
| 234 { | |
| 235 translationsLocal.TryGetValue(translationID, out translation); | |
| 236 } | |
| 237 | |
| 238 if (translation == null) | |
| 239 { | |
| 240 translationsDefault.TryGetValue(translationID, out translation); | |
| 241 } | |
| 242 | |
| 243 return translation; | |
| 244 } | |
| 245 | |
| 246 private static string GetDefaultTranslation(string translationID, string defaultTranslation) | |
| 247 { | |
| 248 return (defaultTranslation != "" && defaultTranslation != null) ? defaultTranslation : GetMissingTranslationMessage(translationID); | |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
249 } |
| 6 | 250 |
| 251 private static string GetMissingTranslationMessage(string translationID) | |
| 252 { | |
| 253 return "++ Missing Translation "+translationID+" ++"; | |
| 254 } | |
| 255 | |
| 256 private static string AddVariablesToTranslation(string translation, object[] replacements) | |
| 257 { | |
| 258 if (translation != null && replacements != null && replacements.Length > 0) | |
| 259 { | |
| 260 translation = String.Format(translation, replacements); | |
| 261 } | |
| 262 | |
| 263 return translation; | |
| 264 } | |
| 265 | |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
266 private static void checkInitialisation() |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
267 { |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
268 if (translationDir==null) |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
269 { |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
270 throw new InvalidOperationException("Translation class has not been initialised"); |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
271 } |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
272 } |
| 6 | 273 |
| 274 /// <summary> | |
| 275 /// Translate an <see cref="ITranslatable"/> item, with optional string replacement | |
| 276 /// </summary> | |
| 277 /// <param name="item"> | |
| 278 /// A <see cref="ITranslatable"/> to set the text for | |
| 279 /// </param> | |
| 280 /// <param name="replacements"> | |
| 281 /// A collection of <see cref="System.Object"/>s that will be used to fill place-holders | |
| 282 /// </param> | |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
283 public static void Translate(ITranslatable item, params object[] replacements) |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
284 { |
| 6 | 285 if (item.Text == "" || item.Text == DIVIDER_STRING) |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
286 { |
| 6 | 287 //it doesn't need translating - either there is no text from the developer or it's a hyphen for a divider |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
288 return; |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
289 } |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
290 |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
291 item.Text = GetTranslation(item.Name, replacements); |
| 6 | 292 } |
| 293 | |
| 294 /// <summary> | |
| 295 /// Get the current local translation language. This is an arbitrary string used in the translation file's name and will not necessarily match the ISO language code. | |
| 296 /// </summary> | |
| 297 /// <returns> | |
| 298 /// The string used in the file name of the current local translation | |
| 299 /// </returns> | |
| 300 public static string GetTranslationLanguage() | |
| 301 { | |
| 302 return lang; | |
|
0
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
303 } |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
304 } |
|
961030992bd2
Initial commit of IBBoard libraries
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
305 } |