[API] #109: find specific languages when generics are specified

CHANGELOG.md

@@ -20,6 +20,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 - `LocalizationManager.Create` methods without `TranslationMemory kind` parameter
 
+### Fixed
+
+- `LocalizationManager.Create("es"` loads `es-ES` if it is the best match (previously, this resulted in a dialog making the user choose)
+
 ### Deprecated
 
 - `LocalizationManager.Create` methods with `TranslationMemory kind` parameter

L10NSharp.sln

@@ -6,7 +6,7 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "L10NSharp", "src\L10NSharp\
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "L10NSharpTests", "src\L10NSharpTests\L10NSharpTests.csproj", "{BCE5B569-057C-4D7E-832E-E44A2DA705AC}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SampleApp", "src\SampleApp\SampleApp.csproj", "{58923B30-FD84-4BCC-85E0-607DCA7E7C95}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SampleApp", "src\SampleApp\SampleApp.csproj", "{58923B30-FD84-4BCC-85E0-607DCA7E7C95}"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ExtractXliff", "src\ExtractXliff\ExtractXliff.csproj", "{E0666C78-B8DC-4232-952C-753940D54921}"
 EndProject
@@ -18,10 +18,10 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "SolutionFolder", "SolutionF
 		.gitattributes = .gitattributes
 		.gitignore = .gitignore
 		CHANGELOG.md = CHANGELOG.md
-		GitVersion.yml = GitVersion.yml
-		README.md = README.md
 		Directory.Build.props = Directory.Build.props
 		Directory.Build.targets = Directory.Build.targets
+		GitVersion.yml = GitVersion.yml
+		README.md = README.md
 	EndProjectSection
 EndProject
 Global
@@ -54,6 +54,17 @@ Global
 		{BCE5B569-057C-4D7E-832E-E44A2DA705AC}.Release|Mixed Platforms.ActiveCfg = Release|Any CPU
 		{BCE5B569-057C-4D7E-832E-E44A2DA705AC}.Release|Mixed Platforms.Build.0 = Release|Any CPU
 		{BCE5B569-057C-4D7E-832E-E44A2DA705AC}.Release|x86.ActiveCfg = Release|Any CPU
+		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Debug|Mixed Platforms.ActiveCfg = Debug|Any CPU
+		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Debug|Mixed Platforms.Build.0 = Debug|Any CPU
+		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Debug|x86.Build.0 = Debug|Any CPU
+		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Release|Any CPU.Build.0 = Release|Any CPU
+		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Release|Mixed Platforms.ActiveCfg = Release|Any CPU
+		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Release|Mixed Platforms.Build.0 = Release|Any CPU
+		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Release|x86.ActiveCfg = Release|Any CPU
 		{E0666C78-B8DC-4232-952C-753940D54921}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{E0666C78-B8DC-4232-952C-753940D54921}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{E0666C78-B8DC-4232-952C-753940D54921}.Debug|Mixed Platforms.ActiveCfg = Debug|Any CPU
@@ -78,15 +89,6 @@ Global
 		{E4BB984D-DFB8-42EF-860D-5A038FF85B1C}.Release|Mixed Platforms.Build.0 = Release|Any CPU
 		{E4BB984D-DFB8-42EF-860D-5A038FF85B1C}.Release|x86.ActiveCfg = Release|Any CPU
 		{E4BB984D-DFB8-42EF-860D-5A038FF85B1C}.Release|x86.Build.0 = Release|Any CPU
-		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Debug|Mixed Platforms.ActiveCfg = Debug|Any CPU
-		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Debug|Mixed Platforms.Build.0 = Debug|Any CPU
-		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Release|Any CPU.Build.0 = Release|Any CPU
-		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Release|Mixed Platforms.ActiveCfg = Release|Any CPU
-		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Release|Mixed Platforms.Build.0 = Release|Any CPU
-		{58923B30-FD84-4BCC-85E0-607DCA7E7C95}.Release|x86.ActiveCfg = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

README.md

@@ -18,7 +18,7 @@ To use L10NSharp in your application, simply call the `Create` method on `Locali
 passing the location of the translation memory files and some other information:
 
 ```csharp
-using (var lm = LocalizationManager.Create(TranslationMemory.XLiff, lang, "SampleApp",
+using (var lm = LocalizationManager.Create(lang, "SampleApp",
     "SampleApp", productVersion, directoryOfInstalledXliffFiles, "MyCompany/L10NSharpSample",
     icon, "[email protected]", "SampleApp")
 {
@@ -33,9 +33,16 @@ By default, `directoryOfInstalledFiles` contains files named `Whatever.lang.xlf`
 are the language tags. These names must match the target-language declared in the XLF
 for lazy loading to work properly. If the target-language is a multi-part tag (like `es-ES`),
 the lang component in the file path may be either the full tag (`Whatever.es-ES.xlf` or
-`es-ES/Whatever.xlf`) or its first component, the actual language tag (`Whatever.es.xlf`
+`es-ES/Whatever.xlf`) or its first component, the bare language tag (`Whatever.es.xlf`
 or `es/Whatever.xlf`).
 
+### Selecting a Language
+
+If an exact match for the requested language is not available, L10NSharp will try to find the best available language. For example, if the client
+requests `es` but only `Whatever.es-ES.xlf` is available, `Whatever.es-ES.xlf` will be loaded automatically, and vice versa. However, if the client
+requests `es` and both `Whatever.es-ES.xlf` and `Whatever.es-MX.xlf` are available, or if no `Whatever.es[-details].xlf` is available, a dialog will
+inform the user that the selected language is not available and prompt the user to select from the available languages.
+
 ## Thread safety
 
 In general, L10NSharp is not written with thread safety in mind; callers should ensure

src/CheckOrFixXliff/Program.cs

@@ -137,7 +137,7 @@ private static void FixBrokenTransUnit(XElement tu, XmlNamespaceManager namespac
 			var targetValue = target.Value;
 			if (!string.IsNullOrWhiteSpace(targetValue))
 			{
-				var targetFixed = XLiffLocalizedStringCache.FixBrokenFormattingString(targetValue);
+				var targetFixed = XliffLocalizedStringCache.FixBrokenFormattingString(targetValue);
 				if (targetFixed != target.Value)
 					target.SetValue(targetFixed);
 			}
@@ -219,7 +219,7 @@ private static ErrorState CheckFormatStringMarkers(string filename)
 				var okay = CheckForExactlyMatchingSubstitutionMarkers(tu.Id, dictSourceMarkers, dictTargetMarkers);
 				if (!okay && retval == ErrorState.Okay)
 					retval = ErrorState.Warning;
-				if (!XLiffLocalizedStringCache.CheckForValidSubstitutionMarkers(dictSourceMarkers.Count, tu.Target.Value, tu.Id, _quiet))
+				if (!XliffLocalizedStringCache.CheckForValidSubstitutionMarkers(dictSourceMarkers.Count, tu.Target.Value, tu.Id, _quiet))
 				{
 					_mangledTargets.Add(tu.Id);
 					retval = ErrorState.Error;

src/ExtractXliff/Program.cs

@@ -121,7 +121,7 @@ private static void Main(string[] args)
 			// to feed into the constructor the LocalizedStringCache that does some heavy lifting for us in
 			// creating the XliffDocument from the newly extracted localized strings.
 			var lm = new XLiffLocalizationManager(_fileOriginal, _fileOriginal, _fileProductVersion);
-			var stringCache = new XLiffLocalizedStringCache(lm, false);
+			var stringCache = new XliffLocalizedStringCache(lm, false);
 			foreach (var locInfo in localizedStrings)
 				stringCache.UpdateLocalizedInfo(locInfo);
 

src/L10NSharp/LocalizationManager.cs

@@ -101,7 +101,14 @@ public static ILocalizationManager Create(TranslationMemory kind, string desired
 			string relativeSettingPathForLocalizationFolder,
 			Icon applicationIcon, string emailForSubmissions, params string[] namespaceBeginnings)
 		{
-			return Create(kind, desiredUiLangId,
+			if (kind != TranslationMemory.XLiff)
+			{
+				throw new ArgumentException($@"Unknown translation memory kind {kind}. Only XLiff
+				 is supported.",
+					nameof(kind));
+			}
+
+			return Create(desiredUiLangId,
 				appId, appName, appVersion, directoryOfInstalledFiles,
 				relativeSettingPathForLocalizationFolder,
 				applicationIcon, emailForSubmissions,

src/L10NSharp/LocalizationManagerInternal.cs

@@ -13,6 +13,7 @@
 using System.Windows.Forms;
 using L10NSharp.UI;
 using L10NSharp.XLiffUtils;
+// ReSharper disable StaticMemberInGenericType - these static fields are parameter-independent
 
 namespace L10NSharp
 {
@@ -35,10 +36,24 @@ internal static class LocalizationManagerInternal<T>
 		/// </summary>
 		internal static ConcurrentDictionary<string, string> MapToExistingLanguage = new ConcurrentDictionary<string, string>();
 
-		// If documents are loaded lazily, this lock must be held while loading one, or while using MapToExistingLanguage
-		// in a way that might cause loading.
+		/// <remarks>
+		/// If documents are loaded lazily, this lock must be held while loading one, or while using MapToExistingLanguage
+		/// in a way that might cause loading.
+		/// </remarks>
 		internal static object LazyLoadLock = new object();
 
+		/// <summary>
+		/// Function to choose a fallback language during construction. Overridable by unit tests.
+		/// </summary>
+		internal static Func<string, Icon, string> ChooseFallbackLanguage = (desiredUiLangId, icon) =>
+		{
+			using (var dlg = new LanguageChoosingDialog(L10NCultureInfo.GetCultureInfo(desiredUiLangId), icon))
+			{
+				dlg.ShowDialog();
+				return dlg.SelectedLanguage;
+			}
+		};
+
 		private static readonly Dictionary<string, ILocalizationManagerInternal<T>> s_loadedManagers =
 			new Dictionary<string, ILocalizationManagerInternal<T>>();
 
@@ -50,7 +65,7 @@ private static ILocalizationManager Create(string desiredUiLangId, string appId,
 			if (string.IsNullOrEmpty(relativeSettingPathForLocalizationFolder))
 				relativeSettingPathForLocalizationFolder = appName;
 			else if (Path.IsPathRooted(relativeSettingPathForLocalizationFolder))
-				throw new ArgumentException("Relative (non-rooted) path expected", nameof(relativeSettingPathForLocalizationFolder));
+				throw new ArgumentException(@"Relative (non-rooted) path expected", nameof(relativeSettingPathForLocalizationFolder));
 
 			var directoryOfWritableTranslationFiles = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
 				relativeSettingPathForLocalizationFolder, "localizations");
@@ -72,11 +87,7 @@ private static ILocalizationManager Create(string desiredUiLangId, string appId,
 
 			if (!IsDesiredUiCultureAvailable(desiredUiLangId))
 			{
-				using (var dlg = new LanguageChoosingDialog(L10NCultureInfo.GetCultureInfo(desiredUiLangId), applicationIcon))
-				{
-					dlg.ShowDialog();
-					desiredUiLangId = dlg.SelectedLanguage;
-				}
+				desiredUiLangId = ChooseFallbackLanguage(desiredUiLangId, applicationIcon);
 			}
 
 			LocalizationManager.SetUILanguage(desiredUiLangId, false);
@@ -609,6 +620,9 @@ public static string GetDynamicStringOrEnglish(string appId, string id, string e
 		/// not yet contain data about this language. In that case, get the lock for
 		/// loading xliff docs, load any relevant ones, and try again.
 		/// </summary>
+		/// <remarks>
+		/// <see cref="XliffLocalizedStringCache.LoadXliffAndUpdateExistingLanguageMap"/> must load "es-ES" before "es" will map to "es-ES".
+		/// </remarks>
 		internal static string MapToExistingLanguageIfPossible(string langId)
 		{
 			if (string.IsNullOrEmpty(langId))

src/L10NSharp/XLiffUtils/XLiffBody.cs

@@ -83,7 +83,7 @@ public ListWrapper TransUnitsForXml
 			get
 			{
 				var result = TransUnitsUnordered.ToList();
-				result.Sort(XLiffLocalizedStringCache.TuComparer);
+				result.Sort(XliffLocalizedStringCache.TuComparer);
 				return new ListWrapper(result, this);
 			}
 		}
@@ -119,10 +119,10 @@ internal XLiffTransUnit GetTransUnitForId(string id)
 		/// </summary>
 		internal XLiffTransUnit GetTransUnitForOrphan(XLiffTransUnit orphan, XLiffBody source)
 		{
-			var terminalIdToMatch = XLiffLocalizedStringCache.GetTerminalIdPart(orphan.Id);
+			var terminalIdToMatch = XliffLocalizedStringCache.GetTerminalIdPart(orphan.Id);
 			var defaultTextToMatch = GetDefaultVariantValue(orphan);
 			return TransUnitsUnordered.FirstOrDefault(tu =>
-				XLiffLocalizedStringCache.GetTerminalIdPart(tu.Id) ==
+				XliffLocalizedStringCache.GetTerminalIdPart(tu.Id) ==
 				terminalIdToMatch // require last part of ID to match
 				&& GetDefaultVariantValue(tu) == defaultTextToMatch // require text to match
 				&& source?.GetTransUnitForId(tu.Id) == null); // and translation does not already have an element for this

src/L10NSharp/XLiffUtils/XLiffLocalizationManager.cs

@@ -136,7 +136,7 @@ internal XLiffLocalizationManager(string appId, string origExtension, string app
 
 			ComponentCache = new Dictionary<IComponent, string>();
 			ToolTipCtrls = new Dictionary<Control, ToolTip>();
-			StringCache = new XLiffLocalizedStringCache(this);
+			StringCache = new XliffLocalizedStringCache(this);
 			LocalizableComponents = new Dictionary<ILocalizableComponent,
 				Dictionary<string, LocalizingInfo>>();
 		}
@@ -209,7 +209,7 @@ private void CreateOrUpdateDefaultXliffFileIfNecessary(
 			var fileStream = File.Open(DefaultStringFilePath, FileMode.Create, FileAccess.ReadWrite, FileShare.None);
 			fileStream.Close();
 
-			var stringCache = new XLiffLocalizedStringCache(this, false);
+			var stringCache = new XliffLocalizedStringCache(this, false);
 
 			var extractedInfo = ExtractStringsFromCode(Name, additionalLocalizationMethods, namespaceBeginnings);
 			if (extractedInfo != null)
@@ -578,7 +578,7 @@ public void SaveIfDirty(ICollection<string> langIdsToForceCreate)
 		{
 			try
 			{
-				((XLiffLocalizedStringCache)StringCache).SaveIfDirty(langIdsToForceCreate);
+				((XliffLocalizedStringCache)StringCache).SaveIfDirty(langIdsToForceCreate);
 			}
 			catch (IOException e)
 			{

src/L10NSharp/XLiffUtils/XLiffLocalizedStringCache.cs

@@ -13,7 +13,7 @@
 namespace L10NSharp.XLiffUtils
 {
 	/// ----------------------------------------------------------------------------------------
-	internal class XLiffLocalizedStringCache : LocalizedStringCache, ILocalizedStringCache<XLiffDocument>
+	internal class XliffLocalizedStringCache : LocalizedStringCache, ILocalizedStringCache<XLiffDocument>
 	{
 		private readonly XLiffTransUnitUpdater _tuUpdater;
 
@@ -40,7 +40,7 @@ internal class XLiffLocalizedStringCache : LocalizedStringCache, ILocalizedStrin
 		/// Loads the string cache from all the specified Xliff files
 		/// </summary>
 		/// ------------------------------------------------------------------------------------
-		internal XLiffLocalizedStringCache(ILocalizationManager owningManager, bool loadAvailableXliffFiles = true)
+		internal XliffLocalizedStringCache(ILocalizationManager owningManager, bool loadAvailableXliffFiles = true)
 		{
 			OwningManager = (XLiffLocalizationManager)owningManager;
 			if (loadAvailableXliffFiles)
@@ -162,20 +162,34 @@ private void MergeXliffFilesIntoCache(IEnumerable<string> xliffFiles)
 		/// (or its primary language, if different) and update MapToExistingLanguage according
 		/// to what we find. 
 		/// Use only from TryGetDocument. Should hold LazyLoadLock.
+		/// Tries to find partial matches, similar to <seealso cref="LocalizationManagerInternal&lt;T&gt;.MapToExistingLanguageIfPossible"/>
 		/// </summary>
 		private void LoadXliffAndUpdateExistingLanguageMap(string langId)
 		{
 			if (!_unloadedXliffDocuments.TryRemove(langId, out string file))
 			{
 				// Often an xliff in a plain lang folder (like "es") contains
 				// a target-language that is more specific (like "es-ES").
-				// If we're asked to try to load the xliff for es-ES and don't find one,
-				// Try loading the one for es.
+				// Another possibility is that the lang folder is "es-ES" but the client is requesting only "es". In either case, try to find a
+				// sensible match automatically before prompting the user. If, however, there is more than one match and no clear best,
+				// allow the user to choose. (https://github.com/sillsdev/l10nsharp/issues/109)
 				var pieces = langId.Split('-');
-				if (pieces.Length <= 1)
-					return;
-				if (!_unloadedXliffDocuments.TryRemove(pieces[0], out file))
-					return;
+				// If we're asked to try to load the xliff for es-ES and don't find one, try loading the one for es.
+				if (pieces.Length == 1 || !_unloadedXliffDocuments.TryRemove(pieces[0], out file))
+				{
+					// Either we were already trying to find 'es' or we could find neither 'es-ES' nor 'es'. Look for 'es-*'.
+					var available = _unloadedXliffDocuments.Keys.Where(key => key.Split('-')[0] == pieces[0]).ToList();
+					if (available.Count == 1)
+					{
+						_unloadedXliffDocuments.TryRemove(available[0], out file);
+					}
+					else
+					{
+						// Loading more than one partial match at this point would arbitrarily map the bare language ID to the first available,
+						// which might not be correct
+						return;
+					}
+				}
 			}
 
 			var xliffDoc = XLiffDocument.Read(file);
@@ -208,6 +222,11 @@ private void LoadXliffAndUpdateExistingLanguageMap(string langId)
 				}
 			}
 
+			if (langId == LocalizationManager.kDefaultLang)
+			{
+				return;
+			}
+
 			XliffDocuments.TryAdd(targetLang, xliffDoc);
 			var defunctUnits = new List<XLiffTransUnit>();
 			foreach (var tu in xliffDoc.File.Body.TransUnitsUnordered.ToList()) // need a list here because we may modify it while enumerating
@@ -216,8 +235,7 @@ private void LoadXliffAndUpdateExistingLanguageMap(string langId)
 				// We assume the default language Xliff has only current IDs, and therefore don't look for orphans in that case.
 				// This guards against cases such as recently occurred in Bloom, where a dynamic ID EditTab.AddPageDialog.Title
 				// was regarded as an obsolete id for PublishTab.Upload.Title
-				if (langId != LocalizationManager.kDefaultLang &&
-				    DefaultXliffDocument.GetTransUnitForId(tu.Id) == null &&
+				if (DefaultXliffDocument.GetTransUnitForId(tu.Id) == null &&
 				    !tu.Id.EndsWith(kToolTipSuffix) && !tu.Id.EndsWith(kShortcutSuffix))
 				{
 					//if we couldn't find it, maybe the id just changed and then if so re-id it.

src/L10NSharp/XLiffUtils/XLiffTransUnitUpdater.cs

@@ -19,13 +19,13 @@ internal class XLiffTransUnitUpdater
 		// with the value of kOSNewline.
 		internal string _literalNewline = "\\n";
 
-		private readonly XLiffLocalizedStringCache _stringCache;
+		private readonly XliffLocalizedStringCache _stringCache;
 		private readonly string                    _defaultLang;
 		private          bool                      _updated;
 
 
 		/// ------------------------------------------------------------------------------------
-		internal XLiffTransUnitUpdater(XLiffLocalizedStringCache cache)
+		internal XLiffTransUnitUpdater(XliffLocalizedStringCache cache)
 		{
 			_stringCache = cache;
 			_defaultLang = LocalizationManager.kDefaultLang;