axuno/SmartFormat v3.0.0-alpha.4

on GitHub

Changes on top of v3.0.0-alpha.3:

1. Further improvement in performance

2. Added LocalizationFormatter (#176)

Features

• Added LocalizationFormatter to localize literals and placeholders
• Added ILocalizationProvider and a standard implemention as LocalizationProvider, which handles resx resource files. A fallback culture can be set. It will be used, in case no item for a certain culture could be found in any of the resources. LocalizationProvider can search an unlimited number of defined resoures.
• SmartSettings were exended with category Localization. That way, custom IFormatters can also make use of localization, if needed.
• Added LocalizationFormattingException, which is derived from FormattingException to easily identify this kind of issues

Examples

Culture-specific results shown here are included in embedded resource files, which are omitted for brevity.

a) Localize pure literals into Spanish:

// culture supplied as a format option
_ = Smart.Format(culture, "{:L(en):WeTranslateText}");
// culture supplied as an argument to the formatter
var culture = CultureInfo.GetCultureInfo("es");
_ = Smart.Format(culture, "{:L:WeTranslateText}");
// result for both: "Traducimos el texto"

b) Localized strings may contain placeholders

_ = Smart.Format("{0} {1:L(es):has {:#,#} inhabitants}", "X-City", 8900000);
// result: "X-City tiene 8.900.000 habitantes"
_ = Smart.Format("{0} {1:L(es):has {:#,#} inhabitants}", "X-City", 8900000);
// result: "X-City has 8,900,000 inhabitants"

c) Localization can be used together with other formatters

_ = Smart.Format("{0:plural:{:L(en):{} item}|{:L(en):{} items}}", 0;
// result for English: 0 items
_ = Smart.Format("{0:plural:{:L(fr):{} item}|{:L(fr):{} items}}", 0;
// result for French: 0 élément
_ = Smart.Format("{0:plural:{:L(fr):{} item}|{:L(fr):{} items}}", 200;
// result for French: 200 éléments

3. Refactored PluralLocalizationFormatter (#209)

• Constructor with string argument for default language is obsolete.
• Property DefaultTwoLetterISOLanguageName is obsolete.
• Culture is now determined in this sequence (same as with LocalizationFormatter):
  
  a) Get the culture from the FormattingInfo.FormatterOptions.
  
  b) Get the culture from the IFormatProvider argument (which may be a CultureInfo) to SmartFormatter.Format(IFormatProvider, string, object?[])
  
  c) The CultureInfo.CurrentUICulture
  

4. Refactored TimeFormatter (#220, #221)

• Constructor with string argument for default language is obsolete.
• Property DefaultTwoLetterISOLanguageName is obsolete.
• Culture is now determined in this sequence (same as with LocalizationFormatter and PluralLocalizationFormatter):
  
  a) Get the culture from the FormattingInfo.FormatterOptions.
  
  b) Get the culture from the IFormatProvider argument (which may be a CultureInfo) to SmartFormatter.Format(IFormatProvider, string, object?[])
  
  c) The CultureInfo.CurrentUICulture
  
• New: With the extended CommonLanguagesTimeTextInfo, TimeFormatter includes French, Spanish, Portuguese, Italian and German as new languages besides English out-of-the-box.
• New: With e.g. TimeFormatter.FallbackLanguage = "en";, this fallback language will be used, if no supported language could be found.
• New: Custom languages can now easily be added to CommonLanguagesTimeTextInfo. Custom languages override built-in definitions.

  var language = "nl"; // dummy - it's English, not Dutch ;-)
  TimeTextInfo custom = new(
      pluralRule: PluralRules.GetPluralRule(language),
      week: new[] { "{0} week", "{0} weeks" },
      day: new[] { "{0} day", "{0} days" },
      hour: new[] { "{0} hour", "{0} hours" },
      minute: new[] { "{0} minute", "{0} minutes" },
      second: new[] { "{0} second", "{0} seconds" },
      millisecond: new[] { "{0} millisecond", "{0} milliseconds" },
      w: new[] { "{0}w" },
      d: new[] { "{0}d" },
      h: new[] { "{0}h" },
      m: new[] { "{0}m" },
      s: new[] { "{0}s" },
      ms: new[] { "{0}ms" },
      lessThan: "less than {0}");
  CommonLanguagesTimeTextInfo.AddLanguage(language, custom)

• Changed:
  a) This notation - using formats as formatter options - was allowed in Smart.Format v2.x, but is now depreciated. It is still detected and working, as long as the format part is left empty

  var formatDepreciated = "{0:time(abbr hours noless)}";

  b) This format string is recommended for Smart.Format v3 and later. It allows for including the language as an option to the TimeFormatter:

  // Without language option:
  var formatRecommended = "{0:time:abbr hours noless:}";
  // With language option:
  var formatRecommended = "{0:time(en):abbr hours noless:}";

• PRs for extending built-in languages are welcome.
• Example:

  var timeSpan = new TimeSpan(1,1,1,1,1)
  Smart.Format("{0:time(en):hours minutes}", timeSpan);
  // result: "25 hours 1 minute"
  Smart.Format("{0:time(fr):hours minutes}", timeSpan);
  // result: "25 heures 1 minute"