Power Fx and CultureInfos

[MikeStall]

I get asked this frequently so wanted to capture an answer somewhere. We'll get this onto official docs.

(Update on 4/21/2023)

Power Fx uses Culture in several places: While parsing, while providing error messages, and at runtime.

• See Global Support for more information.
• Note that Culture is separate from TimeZoneInfo.
• Latest PR to update this is CultureInfo support for errors #1040.
• See MultiCulture1 test for example of setting each of these cultures.

1. While Parsing

Power Fx, like Excel, actually has locale-specific parsing.

This impacts parsing number literals as well as the chaining operator. See: Formula Separators and Chaining operator

For example, Sum(12,34) can be parsed very differently depending on the culture:

1. In en-US, , is an arg separator, so this is two arguments to Sum and parsed as 12+34=46.
2. In fr-FR, , is a decimal separator, so this is parsed as a single argument of 12.34.

The parser mode is determined by:

1. Culture set in ParserOptions or Parse method.
2. Culture passed to Engine.Parse method or CheckResult.SetText(). If null, this can pull a default from Engine.GetDefaultParserOptions().

This should never use Thread.CurrentCulture.

Expressions should be saved in Invariant format so that it's independent of the current user's locale.
See Engine.GetInvariantExpression and GetDisplayExpression for converting.
And then translated back to the user's locale on load.

2. For compiler time error messages and intellisense descriptions back to the expression author.

See string resx resource files in https://github.com/microsoft/Power-Fx/tree/main/src/strings

This is determined by:

1. Defaults to the parser locale
2. Can be an explicit locale. So you can parse in Locale1 and get errors localzed in Locale2.

This is often the same as the parser locale.

Note that Language Service Provider (intellisense) uses parse + error locales. When explicitly provided, error locale will also result in localized intellisense messages.
See ErrorIsLocalized test for example on how to get error and intellisense localized messages.

3. At runtime, for default culture for Value(), Text() etc functions.

These functions can explicitly take a culture parameter. If not specified, they use a "default" runtime culture which can be set at the engine level.

This is determined by:

1. Culture set on RuntimeConfig, which can be passed per-eval. See SymbolExtensions.SetCulture example.
2. Culture set in PowerFxConfig

Assume the runtime culture is en-US:
Value("123,456") + 1 // 123457 - defaults to en-US
Value("123,456", "fr-FR") + 1 // 124.456, explicitly set to fr-FR

These cultures are often the same, but they could be different. For example a maker authoring in jp-JP locale could write Power Fx using fr-FR number literal format , and the expressions read numbers from en-US and write them out in turkish.

More practically, this means that a single expression could run in a loop against 1000s of inputs, and process each in their own culture.

Serializing FormulaValues

FormulaValues can be serialized with FormulaValue.ToExpression. This will return a power fx expression which can then be deserialized via Eval.

This will serialize in an invariant culture, and then can be parsed back with an engine using parser options in invariant culture.
Once the FormulaValue is parsed, it is agnostic to the culture. For example, evalling 12.34 in en-US and 12,34 in fr-FR will produce the same FormulaValue.