Automatic merge of T1.6-186-g21d9ada29 and 13 pull requests

- Pull request #1082 at b191a54: Allow variable water level in glass gauge
- Pull request #1057 at 85bde8e: Switchable brake system
- Pull request #1081 at a8127a1: Brake cuts power unification
- Pull request #1091 at 378be55: Automatic speed control
- Pull request #1122 at 73c47b4: Wagon Size and Centering Controls
- Pull request #1124 at e241a0d: Built-in PBL2 brake controller
- Pull request #1128 at b6c197f: Particle Emitter Overhaul
- Pull request #1158 at 2599bfe: Temporary fix for bug 2121985: F9 TCO out-of-range after resume
- Pull request #1169 at 906f204: Revise TrainCar.SetUpWheels to Better Handle Unusual Rolling Stock
- Pull request #1175 at d28315e: Make Data Logger interval configurable
- Pull request #1176 at 4cd961b: Remove Implicit Requirement for Engine Name to Come After "Engine ("
- Pull request #1178 at 015769e: Fix Diesel RPM Rate of Change
- Pull request #1183 at 41911f1: docs: Add code guidelines for translations

Author: openrails-bot

Docs/Code Guidelines.md

@@ -6,7 +6,7 @@
 - Use the most appropriate logging method:
   - When parsing files, use [file format logging methods](#file-format-logging-methods)
   - Otherwise, use [general logging methods](#general-logging-methods)
-- Use [simple past tense](https://en.wikipedia.org/wiki/Simple_past) with the verb at the front; e.g. "Ignored missing texture file" instead of "Missing texture file was ignored".
+- Use [simple past tense](https://en.wikipedia.org/wiki/Simple_past) with the verb at the front; e.g. "Ignored missing texture file" instead of "Missing texture file was ignored"
 - Do not make reference to the user or Open Rails itself
 - Include the most relevant source file and line number at the end of the message (_file format logging methods_ do this for you)
 
@@ -60,3 +60,89 @@ When parsing files, use the specific logger methods below to automatically inclu
   Trace.TraceWarning("Skipped unknown texture addressing mode {1} in shape {0}", shapeFileName, addressingMode);
   Trace.TraceInformation("Ignored missing animation data in shape {0}", shapeFileName);
   ```
+
+## Translations
+
+- Use translations for all user-visible text
+- Use English (United States) for all translations
+- Use [entire sentences](#entire-sentences) appropriately
+- Use [nested values](#nested-values) appropriately
+- Use [context](#context) appropriately
+- Use [dynamic values](#dynamic-values) appropriately
+
+### Entire sentences
+
+Not all languages put words in the same order, or even have a concept of "words". For this reason, only translate entire sentences. Never concatenate multiple translations to form a longer string of text. [Nested values](#nested-values) are allowed under specific conditions.
+
+### Nested values
+
+In a formatted string, each placeholder is replaced with a nested value, which appears adjacent of the formatting string. For this reason, delimiters are needed to separate nested values from the surrounding text. Otherwise, it does not meet the [entire sentences](#entire-sentences) requirement. For example:
+
+- **Allowed:** Opening "{0}" doors...
+- **Allowed:** Opening doors on: {0}
+- **Not allowed:** Opening {0} doors...
+- **Not allowed:** Opening doors on {0}
+
+### Context
+
+Not all sentences or values which must be translated will make sense when seen on their own. For this reason, additional context is added in the code to provide translators with the necessary information to correctly translate them. The context is only shown to translators and does not form part of the translation itself.
+
+### Dynamic values
+
+Dynamic values are those that depend on the state of the application and can be used stand-alone or as [nested values](#nested-values). They may or may not use [context](#context).
+
+- For boolean values, use two static values
+- For enumerated values, use `GetStringAttribute` and `GetParticularStringAttribute` as attributes and static methods
+- For numeric values with units, use `Format...()` methods from static class `FormatStrings`
+
+### Examples
+
+- For a context-free static sentence:
+  ```csharp
+  Catalog.GetString("Opening doors on left...");
+  ```
+- For a context-free static sentence with a nested value:
+  ```csharp
+  Catalog.GetStringFmt("Opening doors on: {0}", ...);
+  // Shortcut for: string.Format(Catalog.GetString("Opening doors on: {0}"), ...);
+  ```
+- For a context-sensitive static sentence:
+  ```csharp
+  Catalog.GetParticularString("Doors", "Opening on left...");
+  ```
+- For a context-sensitive static sentence with a nested value:
+  ```csharp
+  // No shortcut available, so use:
+  string.Format(Catalog.GetParticularString("Doors", "Open on: {0}"), ...);
+  ```
+- For a context-free boolean dynamic value:
+  ```csharp
+  return doorsOpen ? Catalog.GetString("Doors open") : Catalog.GetString("Doors closed")
+  ```
+- For a context-sensitive boolean dynamic value:
+  ```csharp
+  return doorsOpen ? Catalog.GetParticularString("Doors", "Open") : Catalog.GetParticularString("Doors", "Closed")
+  ```
+- For a context-free enumerated dynamic value:
+  ```csharp
+  enum Actions
+  {
+      [GetString("Doors Left Open")]DoorsLeftOpen,
+      [GetString("Doors Left Close")]DoorsLeftClose,
+  }
+  return GetStringAttribute.GetPrettyName(action);
+  ```
+- For a context-sensitive enumerated dynamic value:
+  ```csharp
+  enum Actions
+  {
+      [GetParticularString("Doors", "Left Open")]DoorsLeftOpen,
+      [GetParticularString("Doors", "Left Close")]DoorsLeftClose,
+  }
+  return GetParticularStringAttribute.GetParticularPrettyName("Doors", action);
+  ```
+- For a numeric unit dynamic value:
+  ```csharp
+  // There are about 30 of these `FormatStrings.Format...()` functions available:
+  return FormatStrings.FormatDistance(distanceM, isMetric)
+  ```

Source/Orts.Common/GetStringAttribute.cs

@@ -52,13 +52,11 @@ public class GetParticularStringAttribute : GetStringAttribute
         public static string GetParticularPrettyName(string context, Enum value)
         {
             var type = value.GetType();
-            string toBeReturned = type.GetField(Enum.GetName(type, value))
+            return type.GetField(Enum.GetName(type, value))
                 .GetCustomAttributes(false)
                 .OfType<GetParticularStringAttribute>()
-                .SingleOrDefault()
+                .FirstOrDefault(attribute => attribute.Context == context)
                 .Name;
-
-            return toBeReturned;
         }
     }
 }