Skip to content

A Civilization-style strategy game about governing Israel from 15 May 1948. Real ministers, real map, every fact sourced. Unity + deterministic C# sim.

17.1 KB
Raw Blame
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Text.RegularExpressions;
using YamlDotNet.Core;
using YamlDotNet.RepresentationModel;

namespace Statecraft.Sim
{
    /// <summary>Brings translations/ to the sim with the content (#1618 step 2; docs/translations.md, "Loading"). Each
    /// language is parsed and checked against the content it translates, then kept in <see cref="Content.Translations"/>,
    /// outside the content hash. Nothing shows them yet: the game's Hebrew still comes from the inline fields, and a
    /// translations/he/ that is present must equal them, so the later steps can switch the source with no text changing.</summary>
    public static class TranslationLoader
    {
        public const string Folder = "translations";

        static readonly string[] LanguageFiles = { Translations.UiFile, Translations.EventsFile, Translations.ContentFile };

        /// <summary>UI keys only Hebrew may translate, for now (owner, 24 October 2026, #1604): the advisors and How to play, and
        /// the encyclopedia that replaced How to play (#1606: once the game shows a translated ui.yaml, this is what keeps it
        /// English or Hebrew, as translations/README.md and tools/translate.py already treat it).</summary>
        public static readonly IReadOnlyList<string> HebrewOnlyUi = new[] { "advisor.", "how_to_play.", "encyclopedia." };

        /// <summary>translations/ beside a folder named content: the repository's beside content/, StreamingAssets/translations
        /// beside StreamingAssets/content. Null for a content folder with another name, such as a test fixture, so a fixture
        /// never picks up translations from wherever it happens to be written.</summary>
        public static string? Beside(string contentRoot)
        {
            var dir = Path.GetFullPath(contentRoot).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
            return Path.GetFileName(dir) == "content" ? Path.Combine(Path.GetDirectoryName(dir)!, Folder) : null;
        }

        static bool Hidden(string path) => Path.GetFileName(path).StartsWith(".", StringComparison.Ordinal);

        /// <summary>The language files under <paramref name="translationsRoot"/>, as "ro/ui.yaml", in ordinal order (none when
        /// it is null or missing). Files at the top (README.md) are not languages, and hidden names (.DS_Store) are system
        /// metadata, so both are passed over. Anything else that is not a language's ui.yaml, events.yaml or content.yaml
        /// is refused rather than skipped, so a misnamed file cannot drop out unnoticed. A folder that cannot be listed is a
        /// <see cref="ContentException"/> too, so it is reported as a content error.</summary>
        public static List<string> Collect(string? translationsRoot)
        {
            try { return CollectFiles(translationsRoot); }
            catch (IOException e) { throw new ContentException(Folder, "(folder)", e.Message); }
            catch (UnauthorizedAccessException e) { throw new ContentException(Folder, "(folder)", e.Message); }
        }

        static List<string> CollectFiles(string? translationsRoot)
        {
            var files = new List<string>();
            if (translationsRoot == null || !Directory.Exists(translationsRoot)) return files;
            foreach (var dir in Directory.GetDirectories(translationsRoot).Where(d => !Hidden(d)))
            {
                var lang = Path.GetFileName(dir);
                if (!Translations.IsLanguage(lang))
                    throw new ContentException($"{Folder}/{lang}", "(folder)", "not a language code (fr, ar, pt-BR)");
                if (Directory.GetDirectories(dir).Any(d => !Hidden(d)))
                    throw new ContentException($"{Folder}/{lang}", "(folder)", "a language folder has no sub-folders");
                foreach (var file in Directory.GetFiles(dir).Where(f => !Hidden(f)))
                {
                    var name = Path.GetFileName(file);
                    if (!LanguageFiles.Contains(name))
                        throw new ContentException($"{Folder}/{lang}/{name}", "(file)", $"a language has only {string.Join(", ", LanguageFiles)}");
                    files.Add(lang + "/" + name);
                }
            }
            files.Sort(StringComparer.Ordinal);
            return files;
        }

        /// <summary>Reads and checks every language in <paramref name="files"/> (as <see cref="Collect"/> lists them, or as a
        /// player's manifest does). <paramref name="readContent"/> reads a content file without hashing it (null: not there);
        /// <paramref name="events"/> are every parsed event, including those the ruleset leaves out.</summary>
        internal static List<TranslationSet> Load(IReadOnlyList<GameEvent> events, Func<string, string?> readContent,
            Func<string, string?> readTranslation, IEnumerable<string> files)
        {
            var languages = new SortedDictionary<string, HashSet<string>>(StringComparer.Ordinal);
            foreach (var f in files)
            {
                var parts = (f ?? "").Split('/');
                if (parts.Length != 2 || !Translations.IsLanguage(parts[0]) || !LanguageFiles.Contains(parts[1]))
                    throw new ContentException($"{Folder}/{f}", "(file)", "not <language>/ui.yaml, events.yaml or content.yaml");
                if (!languages.TryGetValue(parts[0], out var names)) languages[parts[0]] = names = new HashSet<string>(StringComparer.Ordinal);
                if (!names.Add(parts[1])) throw new ContentException($"{Folder}/{f}", "(file)", "listed twice");
            }

            var parsed = new Dictionary<string, YamlNode?>(StringComparer.Ordinal);
            YamlNode? Yaml(string rel)
            {
                if (parsed.TryGetValue(rel, out var cached)) return cached;
                var text = readContent(rel);
                YamlNode? root = null;
                if (text != null)
                {
                    var stream = new YamlStream();
                    try { stream.Load(new StringReader(text)); }
                    catch (YamlException e) { throw new ContentException(rel, $"line {e.Start.Line}", e.InnerException?.Message ?? e.Message); }
                    root = stream.Documents.Count > 0 ? stream.Documents[0].RootNode : new YamlMappingNode();
                }
                return parsed[rel] = root;
            }

            var sets = new List<TranslationSet>();
            foreach (var language in languages)
            {
                string? Text(string name)
                {
                    if (!language.Value.Contains(name)) return null;
                    var where = $"{Folder}/{language.Key}/{name}";
                    try { return readTranslation(language.Key + "/" + name) ?? throw new ContentException(where, "(file)", "listed but missing"); }
                    catch (IOException e) { throw new ContentException(where, "(file)", e.Message); }
                    catch (UnauthorizedAccessException e) { throw new ContentException(where, "(file)", e.Message); }
                }
                var set = Translations.Parse(language.Key, Text(Translations.UiFile), Text(Translations.EventsFile), Text(Translations.ContentFile));
                Translations.CheckDeclaredLanguage(set);
                CheckUi(set);
                CheckEvents(set, events);
                CheckContent(set, Yaml);
                if (set.Lang == Translations.Hebrew) CheckEqualsInlineHebrew(set, events, Yaml);
                sets.Add(set);
            }
            return sets;
        }

        static string Where(TranslationSet set, string file) => $"{Folder}/{set.Lang}/{file}";

        static void CheckUi(TranslationSet set)
        {
            if (set.Lang == Translations.Hebrew) return;
            foreach (var kv in set.Ui)
                if (HebrewOnlyUi.Any(p => kv.Key.StartsWith(p, StringComparison.Ordinal)))
                    throw new ContentException(Where(set, Translations.UiFile), kv.Key,
                        "the advisors and How to play stay English or Hebrew only, for now (owner, 24 October 2026, #1604)");
        }

        // A placeholder as tools/translate.py's TOKEN reads one: braces around anything that is not a brace.
        static readonly Regex Token = new Regex(@"\{[^{}]+\}");

        /// <summary>The English UI table of a checkout (unity/Assets/UI/strings.en.yaml beside the folder holding
        /// <paramref name="contentRoot"/>), or null when there is none, as in a player's StreamingAssets or a test fixture.</summary>
        internal static string? EnglishUi(string contentRoot)
        {
            var parent = Path.GetDirectoryName(Path.GetFullPath(contentRoot).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar));
            var path = parent == null ? null : Path.Combine(parent, "unity", "Assets", "UI", "strings.en.yaml");
            return path != null && File.Exists(path) ? File.ReadAllText(path) : null;
        }

        /// <summary>#2598: every non-Hebrew ui.yaml keys only strings that <paramref name="englishUi"/> (strings.en.yaml) has,
        /// each with as many of each placeholder as the English one, the rule tools/translate.py's _check applies to an
        /// editor save. A hand-edited file is otherwise never compared: a misspelt key leaves the real one in English with no
        /// word, and a dropped or renamed placeholder loses its value or makes string.Format throw (UiText.Format). Hebrew is
        /// held to strings.he.yaml by its own tests.</summary>
        internal static void CheckUiAgainstEnglish(IEnumerable<TranslationSet> sets, string englishUi)
        {
            var english = new Dictionary<string, string>(StringComparer.Ordinal);
            var stream = new YamlStream();
            try { stream.Load(new StringReader(englishUi)); }
            catch (YamlException e) { throw new ContentException("strings.en.yaml", $"line {e.Start.Line}", e.InnerException?.Message ?? e.Message); }
            if (stream.Documents.Count > 0 && stream.Documents[0].RootNode is YamlMappingNode map)
                foreach (var kv in map.Children)
                    if (kv.Key is YamlScalarNode k && kv.Value is YamlScalarNode v) english[k.Value ?? ""] = v.Value ?? "";
            foreach (var set in sets.Where(s => s.Lang != Translations.Hebrew))
            {
                var where = Where(set, Translations.UiFile);
                var unblock = Unblock(set, where, "it", "string");
                foreach (var kv in set.Ui)
                {
                    if (!english.TryGetValue(kv.Key, out var en)) throw new ContentException(where, kv.Key, "strings.en.yaml has no such key" + unblock);
                    var tokens = Token.Matches(en).Cast<Match>().Select(m => m.Value).ToList();
                    var mine = Token.Matches(kv.Value).Cast<Match>().Select(m => m.Value);
                    if (!tokens.OrderBy(t => t, StringComparer.Ordinal).SequenceEqual(mine.OrderBy(t => t, StringComparer.Ordinal), StringComparer.Ordinal))
                        throw new ContentException(where, kv.Key, $"placeholders differ from the English ({(tokens.Count == 0 ? "none" : string.Join(", ", tokens))})" + unblock);
                }
            }
        }

        /// <summary>How a writer unblocks a stale translation without a translator (owner, 1 November 2026: "Refuse + say how
        /// to fix (Recommended)"): delete the entry and the text shows in English. Not for Hebrew, whose files must equal the
        /// inline Hebrew, so a deleted entry is a missing one.</summary>
        static string Unblock(TranslationSet set, string where, string entry, string what) =>
            set.Lang == Translations.Hebrew ? "" : $"; update the entry, or delete {entry} from {where} and the {what} shows in English";

        /// <summary>A translated event exists and translates exactly its options: an event is all or none, so a card never
        /// shows one button in English.</summary>
        static void CheckEvents(TranslationSet set, IReadOnlyList<GameEvent> events)
        {
            var where = Where(set, Translations.EventsFile);
            var unblock = Unblock(set, where, "its block", "event");
            foreach (var t in set.Events)
            {
                var e = events.FirstOrDefault(x => x.Id == t.Id) ?? throw new ContentException(where, t.Id, "no event has this id" + unblock);
                foreach (var o in t.Options)
                    if (!e.Options.Any(x => x.Id == o.Key)) throw new ContentException(where, $"{t.Id}.options.{o.Key}", "the event has no such option" + unblock);
                foreach (var o in e.Options)
                    if (!t.Options.Any(x => x.Key == o.Id))
                        throw new ContentException(where, $"{t.Id}.options.{o.Id}", "required: a translated event translates every option (all or none)" + unblock);
            }
        }

        /// <summary>A content key names a field <see cref="Translations.Fields"/> offers in its file. A file a player does not
        /// ship (<see cref="HebrewOverlay.UnityReads"/>, read there in baked form) is checked where it can be read: the editor,
        /// the CLI and the build gate.</summary>
        static void CheckContent(TranslationSet set, Func<string, YamlNode?> yaml)
        {
            var where = Where(set, Translations.ContentFile);
            var unblock = Unblock(set, where, "it", "field");
            var offered = new Dictionary<string, HashSet<string>?>(StringComparer.Ordinal);
            foreach (var t in set.Content)
            {
                var file = ContentKey.TryParse(t.Key)!.File;   // Parse has checked the key's shape
                if (!offered.TryGetValue(file, out var keys))
                {
                    var root = yaml(file);
                    if (root == null && !HebrewOverlay.UnityReads.Contains(file)) throw new ContentException(where, t.Key, $"no content file {file}" + unblock);
                    offered[file] = keys = root == null ? null : new HashSet<string>(Translations.Fields(file, root).Select(f => f.Key.ToString()), StringComparer.Ordinal);
                }
                if (keys != null && !keys.Contains(t.Key))
                    throw new ContentException(where, t.Key, "not a translatable field: it has no Hebrew form in its file (docs/translations.md, \"Content keys\")" + unblock);
            }
        }

        const string Authoritative = "the inline Hebrew stays authoritative until a later step of #1618 moves it";

        /// <summary>translations/he/ equals the inline Hebrew: the same events with the same title, text, options and review
        /// flag, and the same content fields with the same text and flag, none missing and none extra. A file a player does
        /// not ship is compared where it can be read.</summary>
        static void CheckEqualsInlineHebrew(TranslationSet he, IReadOnlyList<GameEvent> events, Func<string, YamlNode?> yaml)
        {
            var where = Where(he, Translations.EventsFile);
            var inline = events.Where(e => e.TitleHe != "").ToDictionary(e => e.Id, StringComparer.Ordinal);
            foreach (var t in he.Events)
            {
                if (!inline.TryGetValue(t.Id, out var e)) throw new ContentException(where, t.Id, "the event has no inline Hebrew to match");
                var same = t.Title == e.TitleHe && t.Text == e.TextHe && t.Review == e.TextHeReview
                    && t.Options.All(o => e.Options.Single(x => x.Id == o.Key).TextHe == o.Value);
                if (!same) throw new ContentException(where, t.Id, "differs from the event's inline Hebrew; " + Authoritative);
            }
            var translated = new HashSet<string>(he.Events.Select(t => t.Id), StringComparer.Ordinal);
            foreach (var id in inline.Keys.OrderBy(id => id, StringComparer.Ordinal))
                if (!translated.Contains(id)) throw new ContentException(where, id, "missing: the event has inline Hebrew");

            where = Where(he, Translations.ContentFile);
            var mine = he.Content.ToDictionary(t => t.Key, StringComparer.Ordinal);
            var files = HebrewOverlay.Files.Concat(HebrewOverlay.UnityReads).Concat(mine.Keys.Select(k => ContentKey.TryParse(k)!.File))
                .Distinct().OrderBy(f => f, StringComparer.Ordinal);
            foreach (var file in files)
            {
                var root = yaml(file);
                if (root == null) continue;   // not shipped to a player (checked on disk), or not in this content set
                var fields = Translations.Fields(file, root).ToList();
                foreach (var f in fields.Where(f => f.Hebrew != ""))
                {
                    var key = f.Key.ToString();
                    if (!mine.TryGetValue(key, out var t)) throw new ContentException(where, key, "missing: the field has inline Hebrew");
                    if (t.Text != f.Hebrew || t.Review != f.Review) throw new ContentException(where, key, "differs from the inline Hebrew; " + Authoritative);
                }
                foreach (var f in fields.Where(f => f.Hebrew == "" && mine.ContainsKey(f.Key.ToString())))
                    throw new ContentException(where, f.Key.ToString(), "the field has no inline Hebrew to match");
            }
        }
    }
}