view Lang/Translation.cs @ 10:3b7a321e7c4c

Fixes #4 - unexpected exception in translations * Call private language load method to avoid check and exception * Don't null the local table after we've set a default
author IBBoard <dev@ibboard.co.uk>
date Sun, 04 Jan 2009 12:02:36 +0000
parents 562390c8d618
children 0352fa33ee8f
line wrap: on
line source

using System;
using System.IO;
using System.Xml;
using System.Xml.Schema;
using System.Collections.Generic;
using System.Reflection;
using System.ComponentModel;
using IBBoard.IO;
using IBBoard.Logging;
using IBBoard.Xml;

namespace IBBoard.Lang
{
	/// <summary>
	/// A basic string translator that loads a default language and a specified language and returns translated strings that correspond to translation IDs. 
	/// 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
	/// then either a supplied value or a "no validation available" message is returned.
	/// </summary>
	public class Translation
	{		
		private static readonly string DEFAULT_LANGUAGE = "en";
		private static readonly string DIVIDER_STRING = "-";
		private static string lang = "";
		private static DirectoryInfo translationDir;
		private static Dictionary<string, string> translationsLocal;
		private static Dictionary<string, string> translationsDefault;

		/// <summary>
		/// Initialises the translations for the language specified and the default translations so that the Translation class can be used
		/// </summary>
		/// <param name="appPath">
		/// The full path that the application is running from. Must contain the "translations" folder.
		/// </param>
		/// <param name="language">
		/// The language to use as the load language
		/// </param>
		public static void InitialiseTranslations(string appPath, string language)
		{
			InitialiseDefaults(appPath);
			FileInfo file = GetTranslationFile(DEFAULT_LANGUAGE);
			XmlDocument doc = LoadTranslationDocument(file);
			LoadTranslationsFromDocument(doc, translationsDefault);
			LoadTranslationForLanguage(language);
		}
		
		private static void InitialiseDefaults(string appPath)
		{
			string translationPath = appPath.TrimEnd(Constants.DirectoryChar) + Constants.DirectoryString + "translations";

			if (Directory.Exists(translationPath))
			{
				translationsDefault = new Dictionary<string,string>();
				translationsLocal = new Dictionary<string,string>();
				translationDir = new DirectoryInfo(translationPath);
			}
			else
			{
				throw new ArgumentException("Translation path must exist ("+translationPath+")");
			}
		}
		
		private static XmlDocument LoadTranslationDocument(FileInfo file)
		{
			XmlDocument doc = new XmlDocument();
			XmlReaderSettings settings = new XmlReaderSettings();
			settings.XmlResolver = new IBBXmlResolver(translationDir.Parent.FullName);
			settings.ValidationType = ValidationType.DTD;
			settings.ProhibitDtd = false;
			settings.ValidationEventHandler+= new ValidationEventHandler(ValidationEventMethod);
			XmlReader valReader = XmlReader.Create(file.FullName, settings);
			doc.Load(valReader);
			valReader.Close();
			return doc;
		}
		
		private static FileInfo GetTranslationFile(string language)
		{
			FileInfo file = new FileInfo(translationDir.FullName + Constants.DirectoryString + language + ".translation");

			if (!file.Exists)
			{
				throw new FileNotFoundException(language + "translation could not be found in "+translationDir.FullName);
			}
			
			return file;
		}
		
		private static void LoadTranslationsFromDocument(XmlDocument doc, Dictionary<string, string> translationTable)
		{
			try
			{
				XmlNodeList translations = doc.GetElementsByTagName("translation");

				if (translations.Count==0)
				{
					throw new InvalidFileException("No translations found in "+GetLanguageOfDocument(doc)+".translation");
				}
				
				Dictionary<string, string> tempTranslationTable = new Dictionary<string,string>();

				foreach (XmlNode node in translations)
				{
					tempTranslationTable.Add(node.Attributes["id"].Value, node.InnerText);
				}
				
				translationTable.Clear();
				
				foreach (string key in tempTranslationTable.Keys)
				{
					string translation;
					tempTranslationTable.TryGetValue(key, out translation);
					translationTable.Add(key, translation);
				}
			}
			catch(Exception ex)
			{
				throw new XmlParseException("Error while parsing " + GetLanguageOfDocument(doc)+" translation: "+ex.Message);
			}	
		}
		
		private static string GetLanguageOfDocument(XmlDocument doc)
		{
			return doc != null ? doc.DocumentElement.GetAttribute("lang") : "";
		}
		
		private static void ValidationEventMethod(object sender, ValidationEventArgs e)
		{
			//TODO: Fire a validation failure event
    		LogNotifier.Error(typeof(Translation), "Validation Error", e.Exception);
		}

		/// <summary>
		/// Loads translations for a given language and sets them as the local language
		/// </summary>
		/// <param name="translationLang">
		/// The new local language to load
		/// </param>
		public static void LoadTranslation(string translationLanguage)
		{			
			if (translationLanguage == "" || translationLanguage == null)
			{
				throw new ArgumentException("Translation language cannot be null or empty");
			}

			LoadTranslationForLanguage(translationLanguage);
		}
		
		private static void LoadTranslationForLanguage(string translationLanguage)
		{
			checkInitialisation();
			
			if (translationLanguage != DEFAULT_LANGUAGE && translationLanguage != "" && translationLanguage != null)
			{
				FileInfo file = GetTranslationFile(translationLanguage);
				XmlDocument doc = LoadTranslationDocument(file);
				LoadTranslationsFromDocument(doc, translationsLocal);	
			}
			else
			{
				translationsLocal.Clear();				
			}
			
			lang = translationLanguage;
		}

		/// <summary>
		/// 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.
		/// </summary>
		/// <param name="translationID">
		/// The ID to look up the translation for
		/// </param>
		/// <param name="replacements">
		/// A collection of <see cref="System.Object"/>s to replace placeholders with
		/// </param>
		/// <returns>
		/// The translation with the placeholders replaced or a "missing translation" message
		/// </returns>
		public static string GetTranslation(string translationID, params object[] replacements)
		{
			return GetTranslation(translationID, false, replacements);
		}

		/// <summary>
		/// 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.
		/// </summary>
		/// <param name="translationID">
		/// The ID to look up the translation for
		/// </param>
		/// <param name="returnNullOnFail">
		/// TRUE if null should be returned when no translation can be found, or FALSE if a "missing translation" message should be returned
		/// </param>
		/// <param name="replacements">
		/// A collection of <see cref="System.Object"/>s to replace placeholders with
		/// </param>
		/// <returns>
		/// The translation with the placeholders replaced, or a "missing translation" message or null depending on <param name="returnNullOnFail">
		/// </returns>
		public static string GetTranslation(string translationID, bool returnNullOnFail, params object[] replacements)
		{
			return GetTranslation(translationID, returnNullOnFail ? null : "", replacements);
		}

		/// <summary>
		/// 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.
		/// </summary>
		/// <param name="translationID">
		/// The ID to look up the translation for
		/// </param>
		/// <param name="defaultTranslation">
		/// The string to return if no translation can be found. Can be null or any string.
		/// </param>
		/// <param name="replacements">
		/// A collection of <see cref="System.Object"/>s to replace placeholders with
		/// </param>
		/// <returns>
		/// The translation, if one exists, or the supplied default with the placeholders replaced
		/// </returns>
		public static string GetTranslation(string translationID, string defaultTranslation, params object[] replacements)
		{
			checkInitialisation();
			string trans = GetTranslationFromTables(translationID);
			
			if (trans == null)
			{
				trans = GetDefaultTranslation(translationID, defaultTranslation);
			}

			trans = AddVariablesToTranslation(trans, replacements);

			return trans;
		}
		
		private static string GetTranslationFromTables(string translationID)
		{
			string translation = null;
			
			if (translationsLocal!=null)
			{
				translationsLocal.TryGetValue(translationID, out translation);
			}
			
			if (translation == null)
			{
				translationsDefault.TryGetValue(translationID, out translation);
			}
			
			return translation;
		}
		
		private static string GetDefaultTranslation(string translationID, string defaultTranslation)
		{
			return (defaultTranslation != "" && defaultTranslation != null) ? defaultTranslation : GetMissingTranslationMessage(translationID);
		}

		private static string GetMissingTranslationMessage(string translationID)
		{
			return  "++ Missing Translation "+translationID+" ++";
		}
		
		private static string AddVariablesToTranslation(string translation, object[] replacements)
		{
			if (translation != null && replacements != null && replacements.Length > 0)
			{
				translation = String.Format(translation, replacements);
			}
			
			return translation;
		}
		
		private static void checkInitialisation()
		{
			if (translationDir==null)
			{
				throw new InvalidOperationException("Translation class has not been initialised");
			}
		}

		/// <summary>
		/// Translate an <see cref="ITranslatable"/> item, with optional string replacement
		/// </summary>
		/// <param name="item">
		/// A <see cref="ITranslatable"/> to set the text for
		/// </param>
		/// <param name="replacements">
		/// A collection of <see cref="System.Object"/>s that will be used to fill place-holders
		/// </param>
		public static void Translate(ITranslatable item, params object[] replacements)
		{
			if (item.Text == "" || item.Text == DIVIDER_STRING)
			{
				//it doesn't need translating - either there is no text from the developer or it's a hyphen for a divider
				return;
			}
			
			item.Text = GetTranslation(item.Name, replacements);
		}
		
		/// <summary>
		/// 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.
		/// </summary>
		/// <returns>
		/// The string used in the file name of the current local translation
		/// </returns>
		public static string GetTranslationLanguage()
		{
			return lang;
		}
	}
}