ILocalizationFileSystem

ILocalizationFileSystem is the interface for providing access to localization resources.

/// <summary>Interface to file system, such as OS, Microsoft.Extensions.FileSystem, embedded resources file-system.</summary>
public interface ILocalizationFileSystem
{
    /// <summary>Try list files at <paramref name="path"/>.</summary>
    /// <param name="path">path, "" for root. Slash '/' is directory separator, e.g. "path/path".</param>
    /// <param name="files">File names relative to root.</param>
    /// <exception cref="Exception">On unexpected error.</exception>
    bool TryListFiles(string path, [NotNullWhen(true)] out string[]? files);

    /// <summary>Try list sub-directories of <paramref name="path"/>.</summary>
    /// <param name="path">path, "" for root. Slash '/' is directory separator, e.g. "path/path".</param>
    /// <param name="directories">Directory names relative to root.</param>
    /// <exception cref="Exception">On unexpected error.</exception>
    bool TryListDirectories(string path, [NotNullWhen(true)] out string[]? directories);

    /// <summary>Try open <paramref name="filepath"/>.</summary>
    /// <param name="filepath">Relative file path, "" for root. Slash '/' is directory separator, e.g. "path/path".</param>
    /// <exception cref="Exception">On unexpected error.</exception>
    bool TryOpen(string filepath, [NotNullWhen(true)] out Stream stream);
}

LocalizationFileSystem.ApplicationRoot represents all the files at the application root.

// Create filesystem
ILocalizationFileSystem fs = LocalizationFileSystem.ApplicationRoot;
// Create localization
ILocalization localization = new Localization().AddFileSystem(fs);

.Cached(cacheLists, cacheFiles) decorates file system to cache listings and/or files.

// Create filesystem
ILocalizationFileSystem fs = LocalizationFileSystem.ApplicationRoot.Cached(cacheLists: true, cacheFiles: true);
// Create localization
ILocalization localization = new Localization().AddFileSystem(fs);

LocalizationFileSystem.ApplicationRootCached is the singleton where file lists are already cached.

ILocalization localization = new Localization().AddFileSystem(LocalizationFileSystem.ApplicationRootCached);

Localization.Default is preconfigured with LocalizationFileSystem.ApplicationRoot. The reference can be removed if it's not desired for the deployment.

Localization.Default.Files.FileSystems.Remove(LocalizationFileSystem.ApplicationRoot);

If application localization files are immutable, as they typically are, and the file tree is vast, then it may be better to replace filesystem with cached version.

Localization.Default.Files.FileSystems.Remove(LocalizationFileSystem.ApplicationRoot);
Localization.Default.Files.FileSystems.Add(LocalizationFileSystem.ApplicationRootCached);

LocalizationFileSystem(path, name) constructs access to file tree at a specific path.

// Create filesystem
ILocalizationFileSystem fs = new LocalizationFileSystem("C:\\", name: "Root");
// Create localization
ILocalization localization = new Localization().AddFileSystem(fs);

LocalizationMsFileSystem(fileProvider) (Avalanche.Localization.Extensions.dll) adapts IFileProvider to ILocalizationFileSystem.

// Create file provider
IFileProvider fileProvider = new PhysicalFileProvider(AppDomain.CurrentDomain.BaseDirectory);
// Adapt to localization file system
ILocalizationFileSystem fs = new LocalizationMsFileSystem(fileProvider);
// Create localization
ILocalization localization = new Localization()
    .AddFileSystem(fs)
    .AddFilePatterns("Resources/{Key}", "Resources/{Culture}/{Key}");

LocalizationFileSystemEmbedded(assemblies) adds access to embedded resources of one or more specific assemblies.

// Get assembly reference
Assembly assembly = typeof(localizationfilesystem).Assembly;
// Create filesystem
ILocalizationFileSystem fs = new LocalizationFileSystemEmbedded(assembly)
    .Cached(cacheLists: true, cacheFiles: true);
// Create localization
ILocalization localization = new Localization()
    .AddFileSystem(fs)
    .AddFilePatterns("*/*.Resources.{Key}", "*/*.Resources.{Culture}.{Key}", "*/{Key}", "*/{Key}.{Culture}");

└── docs
    ├── docs/docs.Resources.fi.Namespace.yaml
    ├── docs/docs.Resources.sv.Namespace.yaml
    └── docs/docs.Resources.Namespace.yaml

LocalizationFileSystemEmbedded.AppDomain provides access to all embedded resources of all assemblies in current AppDomain. Note that, if appdomain loads additional assemblies at run-time, then it shouldn't be cached.

// Create filesystem
ILocalizationFileSystem fs = LocalizationFileSystemEmbedded.AppDomain;
// Create localization
ILocalization localization = new Localization().AddFileSystem(fs);

├── System.Linq/
│   ├── FxResources.System.Linq.SR.resources
│   ├── ILLink.Descriptors.xml
│   └── ILLink.Substitutions.xml
...

.AddFileSystemWithPattern(filesystem, patterns) adds to .Files.FileProviders a file system with usage of specific patterns. Patterns are not applied to any other configured file system.

// Create localization
ILocalization localization = new Localization()
    .AddFileFormat(LocalizationFileFormatYaml.Instance)
    .AddFileSystemWithPattern(LocalizationFileSystemEmbedded.AppDomain, "*/*.Resources.{Key}", "*/*.Resources.{Culture}.{Key}", "*/{Key}", "*/{Key}.{Culture}");

Listing files

.ListFiles(path) lists files at path.

foreach (string filename in LocalizationFileSystem.ApplicationRoot.ListFiles("")!)
    WriteLine(filename);

.ListAllFiles(path) lists all files recursively starting at path.

foreach (string filename in LocalizationFileSystem.ApplicationRoot.ListAllFiles("")!)
    WriteLine(filename);

Resources/Namespace.sv.yaml
Resources/Namespace.yaml

.ListDirectories(path) lists directories path.

foreach (string filename in LocalizationFileSystem.ApplicationRoot.ListDirectores("")!)
    WriteLine(filename);

.ListAllDirectories(path) lists all directories recursively starting at path.

ILocalizationFileSystem fs = LocalizationFileSystem.ApplicationRoot.Cached(true, true);
foreach (string filename in fs.ListAllDirectories("")!)
    WriteLine(filename);

.VisitTree(path) visits tree of directories and files.

ILocalizationFileSystem fs = LocalizationFileSystem.ApplicationRoot.Cached(true, true);
foreach (var line in fs.VisitTree(""))
    WriteLine(line);

.PrintTree(path) prints as a tree.

ILocalizationFileSystem fs = LocalizationFileSystem.ApplicationRoot.Cached(true, true);
WriteLine(fs.PrintTree(""));

├── Resources
│   ├── fi
│   │   └── Namespace.yaml
│   ├── sv
│   │   └── Namespace.yaml
│   └── Namespace.yaml

.PrintTree(path, format) prints as a tree with full paths names.

ILocalizationFileSystem fs = LocalizationFileSystem.ApplicationRoot.Cached(true, true);
WriteLine(fs.PrintTree("", format: LocalizationFileSystemPrintTreeExtensions.PrintFormat.DefaultLong));

├── Resources/
│   ├── Resources/fi/
│   │   └── Resources/fi/Namespace.yaml
│   ├── Resources/sv/
│   │   └── Resources/sv/Namespace.yaml
│   └── Resources/Namespace.yaml

Note

Path separator is forward slash '/'.

Opening files

.Open(path) opens a stream to a file.

ILocalizationFileSystem fs = LocalizationFileSystem.ApplicationRoot;
using Stream? stream = fs.Open("Resources/Namespace.yaml");

.ReadFullypen(path) reads a file fully.

ILocalizationFileSystem fs = LocalizationFileSystem.ApplicationRoot;
byte[] data = fs.ReadFully("Resources/Namespace.yaml");

Full Example

Full example

using System.Globalization;
using System.Reflection;
using Avalanche.Localization;
using Avalanche.Utilities;
using Avalanche.Utilities.Provider;
using Microsoft.Extensions.FileProviders;
using static System.Console;

class localizationfilesystem
{
    public static void Run()
    {
        {
            // <00>
            // Create filesystem
            ILocalizationFileSystem fs = LocalizationFileSystem.ApplicationRoot;
            // Create localization
            ILocalization localization = new Localization().AddFileSystem(fs);
            // </00>
        }
        {
            // <01>
            // Create filesystem
            ILocalizationFileSystem fs = LocalizationFileSystem.ApplicationRoot.Cached(cacheLists: true, cacheFiles: true);
            // Create localization
            ILocalization localization = new Localization().AddFileSystem(fs);
            // </01>
        }
        {
            // <01B>
            ILocalization localization = new Localization().AddFileSystem(LocalizationFileSystem.ApplicationRootCached);
            // </01B>
        }
        {
            // <1C>
            Localization.Default.Files.FileSystems.Remove(LocalizationFileSystem.ApplicationRoot);
            // </1C>
        }
        {
            // <1D>
            Localization.Default.Files.FileSystems.Remove(LocalizationFileSystem.ApplicationRoot);
            Localization.Default.Files.FileSystems.Add(LocalizationFileSystem.ApplicationRootCached);
            // </1D>
        }
        {
            // <02>
            // Create filesystem
            ILocalizationFileSystem fs = new LocalizationFileSystem("C:\\", name: "Root");
            // Create localization
            ILocalization localization = new Localization().AddFileSystem(fs);
            // </02>
        }
        {
            // <03>
            // Create file provider
            IFileProvider fileProvider = new PhysicalFileProvider(AppDomain.CurrentDomain.BaseDirectory);
            // Adapt to localization file system
            ILocalizationFileSystem fs = new LocalizationMsFileSystem(fileProvider);
            // Create localization
            ILocalization localization = new Localization()
                .AddFileSystem(fs)
                .AddFilePatterns("Resources/{Key}", "Resources/{Culture}/{Key}");
            // </03>
        }
        {
            // <04>
            // Get assembly reference
            Assembly assembly = typeof(localizationfilesystem).Assembly;
            // Create filesystem
            ILocalizationFileSystem fs = new LocalizationFileSystemEmbedded(assembly)
                .Cached(cacheLists: true, cacheFiles: true);
            // Create localization
            ILocalization localization = new Localization()
                .AddFileSystem(fs)
                .AddFilePatterns("*/*.Resources.{Key}", "*/*.Resources.{Culture}.{Key}", "*/{Key}", "*/{Key}.{Culture}");
            // </04>
            WriteLine(fs.PrintTree("", format: LocalizationFileSystemPrintTreeExtensions.PrintFormat.DefaultLong));
            // Open each file in assembly
            foreach (string resourceName in fs.ListAllFiles("")) fs.ReadFully(resourceName);
        }
        {
            // <05>
            // Create filesystem
            ILocalizationFileSystem fs = LocalizationFileSystemEmbedded.AppDomain;
            // Create localization
            ILocalization localization = new Localization().AddFileSystem(fs);
            // </05>
            WriteLine(fs.PrintTree("", format: LocalizationFileSystemPrintTreeExtensions.PrintFormat.DefaultLong));
            // Open each file in appdomain
            foreach (string resourceName in fs.ListAllFiles("")) fs.ReadFully(resourceName);
        }
        {
            // <06>
            // Create localization
            ILocalization localization = new Localization()
                .AddFileFormat(LocalizationFileFormatYaml.Instance)
                .AddFileSystemWithPattern(LocalizationFileSystemEmbedded.AppDomain, "*/*.Resources.{Key}", "*/*.Resources.{Culture}.{Key}", "*/{Key}", "*/{Key}.{Culture}");
            // </06>
            // Print Text
            WriteLine(localization.LocalizedTextCached[("", "Namespace.Apples")].Print(CultureInfo.InvariantCulture, null)); // "Hello World"
        }

        {
            // <10>
            foreach (string filename in LocalizationFileSystem.ApplicationRoot.ListFiles("")!)
                WriteLine(filename);
            // </10>
        }
        {
            // <11>
            foreach (string filename in LocalizationFileSystem.ApplicationRoot.ListAllFiles("")!)
                WriteLine(filename);
            // </11>
        }
        {
            // <12>
            foreach (string filename in LocalizationFileSystem.ApplicationRoot.ListDirectores("")!)
                WriteLine(filename);
            // </12>
        }
        {
            // <13>
            ILocalizationFileSystem fs = LocalizationFileSystem.ApplicationRoot.Cached(true, true);
            foreach (string filename in fs.ListAllDirectories("")!)
                WriteLine(filename);
            // </13>
        }
        WriteLine(); WriteLine();
        {
            // <14>
            ILocalizationFileSystem fs = LocalizationFileSystem.ApplicationRoot.Cached(true, true);
            foreach (var line in fs.VisitTree(""))
                WriteLine(line);
            // </14>
        }
        WriteLine(); WriteLine();
        {
            // <15>
            ILocalizationFileSystem fs = LocalizationFileSystem.ApplicationRoot.Cached(true, true);
            WriteLine(fs.PrintTree(""));
            // </15>
        }
        WriteLine(); WriteLine();
        {
            // <16>
            ILocalizationFileSystem fs = LocalizationFileSystem.ApplicationRoot.Cached(true, true);
            WriteLine(fs.PrintTree("", format: LocalizationFileSystemPrintTreeExtensions.PrintFormat.DefaultLong));
            // </16>
        }
        WriteLine(); WriteLine();
        {
            // <20>
            ILocalizationFileSystem fs = LocalizationFileSystem.ApplicationRoot;
            using Stream? stream = fs.Open("Resources/Namespace.yaml");
            // </20>
        }
        {
            // <21>
            ILocalizationFileSystem fs = LocalizationFileSystem.ApplicationRoot;
            byte[] data = fs.ReadFully("Resources/Namespace.yaml");
            // </21>
        }

    }
}