Refactoring Report

This report details a refactoring required due to unexpected behaviour of the library. May it serve as an RFC.

Problem

Language keys passed to the library are not honoured by default - they are reformatted. This creates problems on certain systems, where filesystems are case sensitive and so reformatting causes the internationalisation files to not be found. This is considered unexpected behaviour.

Expectations

The default behaviour should be to use the provided keys as they are, not to transform them or mutate them in any way automatically. Such behaviours should either be opt-in or left to the end user.

Proposed Solutions

In order of descending difficulty (which is proportional to effectiveness):

1. Remove automatic formatting from the base library altogether, and move to a plugin of its own

• Rationale: It should be left to the end user. As per the philosophy that libraries should be general tools from which users can build programs, specialized features merely add to overhead. See: "UNIX Style, or cat -v Considered Harmful" by Robert Pike.
• Implementation: It would be relatively easy to remove from the base library, as all that takes is to rip out all the involved code and redirect the following functions to use the given keys directly rather than the output. It would also be relatively easy to convert to its own program.
• Compatibility: This is a breaking change, and should be done as part of a major release. Until the next major release, the functions should remain present, but with a warning added that they will be removed and put into their own plugin.

2. Make using the given keys the default behaviour, and make all others opt-in rather than opt-out

• Rationale: It would be much less problematic to implement and require less changes to make these features the opt-out and to make the expected behaviour, which is already implemented, the default.
• Implementation: All that is required would be to make the opt-out behaviour the default, and convert the alternate behaviours to their own opt-in switches.
• Compatibility: This is perfectly backwards compatible - all that is necessary to port end projects from the prior version to this proposed version would be to invert the options, assuming they want this behaviour. Code that is already opting-out or does not need the alternate behaviours but just uses the default anyway would remain intact.

Additional Context

See: i18next-fs-background#14.