Crate lingora

Expand description

§lingora

Version

Note: This is a work in progress, and is not yet ready for general use.

Despite the test suite, not all functionality has been tested, and there are likely to be bugs.

lingora is a free and open-source localization management program that analyses fluent translation files highlighting discrepancies between reference and target language files.

lingora is designed primarily to be used as a command line tool, but also provides a graphical user interface.

linux | macos | windows

§Status

Packaged builds have not been tested; links are provided in the latest github build, so check the latest Build Dioxus Desktop App action for those, or (preferably at the moment) build from source.
There will be ongoing development, particularly in cross-checks between reference and target files.
Please report any issues or feature requests on the GitHub Issues

§Operation

lingora compares the entries of a reference translation file against one or more target translation files.

A Lingora.toml file can be used to define the reference translation file, and target translation files (or search paths).

If the Lingora.toml file exists in the current working directory then it will be used. An explicit config file can be provided using the --config=path/to/your-config.toml command line argument. If no config file exists then sensible defaults will be used.

It is recommended that projects provide an explicit Lingora.toml file minimally specifying the reference translation file so that all other files are compared against it, rather than the locale of a user’s workstation, which would vary from user to user.

By default (i.e., no toml file exists, or is specified) lingora will look for the translation files in ./i18n/ and it will use <current_system_locale>.ftl as the reference translation file.

Command line arguments can be used to override config file settings, with -r path/to/reference_file.ftl and -t path/to/target_file.ftl command line arguments. -t may also specify a folder, in which case all *.ftl files under that folder will be used as targets. The reference and target file names are expected to use the <language>-<locale> naming convention.

§Additional functionality

lingora can create a config.rs source file containing a function to create an I18nConfig for the dioxus-i18n crate.
A GUI interface, to browse files can be invoked with the --output=gui or -o gui command line argument.

§Command line arguments

To list help:
```
lingora --help
```
The default run looks at all ftl files in the ./i18n/ folder, looking for a <current_system_locale>.ftl for the reference file. Only one <current_system_locale>.ftl must exist for this command to run successfully. Output is to stdout.
```
lingora
# or, by redirecting stdout:
lingora > i18n-errors.txt
```
To get the result of an analysis, but not see the details use the --output=silent option. This command does not output anything unless there are inconsistencies in or between the reference and/or target folders, in which case an error return of Error: IntegrityErrorsDetected is displayed.
```
lingora -o silent
```
To specify the reference locale: note this looks for target ftl files in the ./i18n/ folder.
```
lingora -r ./i18n/en/en-GB.ftl
```
To specify reference and target(s): note -t ... can be a folder, in which case a deep search for all .ftl files within the folder is performed.
```
lingora -r ./i18n/en/en-GB.ftl -t ./i18n/en/en-AU.ftl -t ./i18n/it/it.ftl
```
To output an opininated I18nConfig initialisation function: Output is to the provide path. The output settings can be modified in the Lingora.toml configuration file.
```
lingora --dioxus-i18n=path/to/your_i18n_config.rs
```
To use a config file, other than ./Lingora.toml. Note, if Lingora.toml exists in the current working directory, then it will be used by default without specifying explicitly in this command line argument.
```
lingora --config=path/to/your_config.toml
```
The override the default root folder (./i18n/). Note any default root folder is not used if any targets (--target=... / -t ...) are provided.
```
lingora --root=path/to/your_root_folder
```
To run the desktop application, use the --output=gui option:
```
lingora -o gui
```

§Developmemt

cargo test
cargo llvm-cov

Module	Description	Notes
root	Root module
config	Interpret command line arguments and `Lingora.toml` file	1
domain	Domain logic	2
domain/fluent	Fluent file handling
domain/integrity	Integrity checking data structures
gui	Graphical user interface	3
output	Output handling	4

The config module is responsible for interpreting the command line arguments and the Lingora.toml file. The Lingora.toml file can be in the current working directory, or specified with the --config=path/to/your-config.toml argument. arguments.rs is the structure populated by clap. interim_settings.rs is built from the Lingora.toml config file sourced from:
- the –config=path/to/your-config.toml argument, or, if not provided.
- the Lingora.toml file in the current working directory, or, if not provided.
- default settings, which are described in the default_lingora.toml file. settings.rs is the final settings used by the program, which are built from interim_settings.rs and arguments.rs.
The domain module is responsible for the core logic of the program. It compares the reference and target files, and creates the resultant integrity checks. analysis.rs is the resultant analysis of all files, as formed from their respective integrity checks and cross-checks.
The gui module is responsible for the graphical user interface. components contains the various components used in the GUI. state.rs is the user interaction and subseqent current selections.
The output module provides formatted output of the analysis and output of the I18nConfig function call.

§Build

cargo binstall dioxus-cli
dx build --release
# dx bundle // Still in development

§Lingora.toml

# The `Lingora.toml` file can be provided through the `--config=path/to/config` command or,
# by default, as `Lingora.toml` in the current working directory.
#
# The default values, if not provided explicitly or by default, are shown in this example file.

# Default runtime arguments
[lingora]

# The default root path to look for reference and target translation files, if they are not
# explicitly provided in command line arguments, or in the `Lingora.toml` file.
root = "./i18n/"

# The default reference file will be <syslocale.ftl> (whichever the current system locale is)
# searched for in any paths provided in the target list.
# It is recommended to define the reference language file for any projects so that all
# translations can be compared against a definitive translation file.
#
# This can be overridden with the `-r path/to/reference.ftl` command line attribute.
#
# Example:
# reference = "path/to/reference.ftl"

# A list of target translation files. Entries can also be folders, in which case all
# `*.ftl` files will be treated as target translation files.
#
# By default `Lingora` will search all files under the `root` folder (see `root` above).
#
# This can be overridden with the `-t path/to/target1.ftl -t path/to/target1.ftl -t path/to/folder`
# command line attribute.
#
# Example:
# targets = ["path/to/target1.ftl", "path/to/target1.ftl", "path/to/folder"]
# targets = ["./i18n] # default assuming default root.

# dioxus-i18n settings. These settings are only applicable if the `--dioxus-i18n`
# command line argument is provide.
#
[dioxus_i18n]
# Which type of `with_locale` method to use:
#
# Valid values are:
#   - includestr
#   - pathbuf
#   - auto
#
# `includestr` will include a config entry for the reference and target files using
# the `include_str!("path/to/file")` macro.
#
# `pathbuf` will include a config entry for the reference and target files using
# `PathBuf::from("path/to/file")`
#
# `auto` will include a `with_auto_locales(PathBuf::from("path/to/targetfolder")`
# for each folder provided in targets.
#
with_locale = "auto"

# Is is possible to share resources (include_str! or PathBuf). This is useful when,
# for example, a "reference file" for a specific locale is used, but a generic
# entry is required as a catch-all for all other (unspecified) locales in the same
# primary language. The format of each entry is ("<virtual-langid>", "<concrete-langid>"),
# where <concrete-id> was previously defined via `with_locale`.
#
# Example:
# shares = [("en", "en-GB"), ("it", "it-IT")]
shares = []

# The fallback translation file to be used if a match isn't found in the config
# for the requested language.
#
# Example:
# fallback = en-GB
#
# fallback = <locale from reference-file name>

Structs§

App
Arguments

Enums§

AppError
OutputMode

Crate lingoraCopy item path