PhoneticFlow 2.0.0

PhoneticFlow

PhoneticFlow is a dependency-free .NET 10 (C#) library for phonetic text conversion, supporting English, Spanish, Portuguese (Brazilian), and French. No external NLP or language-model dependencies are required — everything ships inside the NuGet package.

English uses the Lytspel respelling system, a clean port of the original Python/Perl/Haskell project by Christian Siefkes (ISC license — see LICENSE.txt). Spanish, Portuguese, and French use a left-to-right grapheme-to-phoneme (G2P) transducer built into the library.

Project layout

src/
├── PhoneticFlow.slnx               Solution file
├── LICENSE.txt, README.md, .gitignore
├── PhoneticFlow/                   Class library (the NuGet package)
│   ├── Language.cs                 Enum: English | Spanish | Portuguese | French
│   ├── IPhoneticEngine.cs          Conversion interface
│   ├── PhoneticEngineFactory.cs    Factory: PhoneticEngineFactory.Create(Language.X)
│   ├── PhoneticConverter.cs        Text tokeniser + paragraph converter
│   ├── PhoneticDictionary.cs       English dictionary engine (Lytspel)
│   ├── Engines/
│   │   ├── EnglishEngine.cs        Wraps PhoneticDictionary as IPhoneticEngine
│   │   ├── RuleBasedEngine.cs      Left-to-right G2P transducer base class
│   │   ├── SpanishEngine.cs        Spanish G2P rules
│   │   ├── PortugueseEngine.cs     Brazilian Portuguese G2P rules
│   │   └── FrenchEngine.cs         French G2P rules
│   └── data/phoneticflow-dict.csv  Embedded Lytspel dictionary (~2.2 MB)
├── PhoneticFlow.Tests/             xUnit tests (English + multilingual)
└── PhoneticFlow.Sample/            Console app demonstrating all languages

All commands below are run from inside src/ (where PhoneticFlow.slnx lives).

Note: PhoneticFlow/LICENSE.txt and PhoneticFlow/README.md are local copies of the root-level files, required because dotnet pack fails with NU5019 on some SDK versions when referencing files outside the project directory. Keep both copies in sync when editing.

Installing

dotnet add package PhoneticFlow

Usage

English (dictionary-based)

using PhoneticFlow;

// Default constructor uses English
var converter = new PhoneticConverter();
string result = converter.Convert("Hello world. This is a test.");
// "Heló wurld. Thiss is a test."

PhoneticConverter is stateful (tracks sentence boundaries across calls). Create one instance per document/thread and reuse it across paragraphs. Call Reset() to clear sentence-boundary tracking when starting an unrelated piece of text.

Other languages

using PhoneticFlow;

// Spanish
var es = new PhoneticConverter(PhoneticEngineFactory.Create(Language.Spanish));
es.Convert("Hola mundo. El queso y la cerveza son deliciosos.");
// "Ola mundo. El keso y la serbesa son delisiosos."

// Brazilian Portuguese
var pt = new PhoneticConverter(PhoneticEngineFactory.Create(Language.Portuguese));
pt.Convert("Olá mundo. O churrasco e a caipirinha são deliciosos.");
// "Ola mundo. O xurrasko e a kaipirinya saun delisiozos."

// French
var fr = new PhoneticConverter(PhoneticEngineFactory.Create(Language.French));
fr.Convert("Bonjour le monde. Le château est magnifique au bord de l'eau.");
// "BoNzhur le moNd. Le shato es manyifike o bor de l'o."

Checking the active language

var converter = new PhoneticConverter(PhoneticEngineFactory.Create(Language.French));
Console.WriteLine(converter.Language); // French

Looking up individual English words

var dict = PhoneticDictionary.Shared;
string? converted = dict.Lookup("hello"); // "heló"
string? unknown   = dict.Lookup("zzzznotaword"); // null

Custom part-of-speech resolution (English)

Some English words have more than one Lytspel spelling depending on grammatical role — e.g. "abstract" (adjective/noun "ábstract" vs. verb "abstract"). The original Lytspel resolves this with spaCy (NLP). PhoneticFlow uses a deterministic default (noun-first fallback chain) as a known simplification. Supply your own resolver if you have a POS tagger available:

PosResolver preferVerb = (word, variants) =>
    variants.TryGetValue("v", out var v) ? v : variants.Values.First();

var dict = new PhoneticDictionary(preferVerb);
var converter = new PhoneticConverter(dict);

G2P rule coverage (non-English languages)

The rule-based engines cover the most frequent phonetic patterns for each language. Key rules per language:

Spanish (Latin-American standard)

• h → silent; v → b; z → s (seseo); ll → y (yeísmo)
• c + e/i → s; c elsewhere → k; qu + e/i → k
• g + e/i → j (/x/); gu + e/i → g (u silent); ñ → ny

Portuguese (Brazilian standard)

• ch → x (/ʃ/); nh → ny (/ɲ/); lh → ly (/ʎ/)
• s between vowels → z; ss between vowels → s; ç → s
• ão → aun; ã → an (nasal vowels); x between vowels → z
• ti / di → tchi / dji (BP palatalisation)

French

• eau / au → o; ou → u; oi → wa; eu → ö
• Nasal vowels: an/en → aN; in/ain → iN; on → oN
• Silent final consonants: s, t, d, x, z, p; verb ending -ent → silent
• ch → sh; gn → ny; j / g + e/i → zh (/ʒ/); h → silent

Limitation: G2P rules cover common patterns (~80% of everyday vocabulary). Loanwords, irregular forms, and homographs may not be handled correctly. For production use at scale, complement with a language-specific exception dictionary or a morphological tagger.

Known limitations

• English POS tagging. Ambiguous English words use a noun-first heuristic instead of real grammatical analysis. Most noticeable: the pronoun "I" (Lytspel: "Y") may render as "I" unless a custom PosResolver is supplied.
• Plain text only. HTML and EPUB conversion are not included.
• Library only — no web or CLI component.

Building from source

cd src
dotnet build PhoneticFlow.slnx
dotnet test  PhoneticFlow.slnx
dotnet run   --project PhoneticFlow.Sample

Packing the NuGet package

dotnet pack PhoneticFlow/PhoneticFlow.csproj -c Release -o ../artifacts

Produces PhoneticFlow.<version>.nupkg (+ .snupkg symbols) in ../artifacts:

dotnet nuget push ../artifacts/PhoneticFlow.<version>.nupkg \
  --api-key <YOUR_API_KEY> \
  --source https://api.nuget.org/v3/index.json

Attribution

The English phonetic dictionary (PhoneticFlow/data/phoneticflow-dict.csv, ~107,000 entries) and core conversion algorithm are derived from the Lytspel project by Christian Siefkes, licensed under the ISC license. See LICENSE.txt for the full notice.