Merge pull request #46 from jakeboone02/i18n

Internationalization support

Author: jakeboone02

CHANGELOG.md

@@ -7,7 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-N/A
+### Added
+
+- [#46] `parseIngredient` now accepts `Array<string>` as well as `string`. Each element of the array is treated as a single ingredient line.
+- [#46] Internationalization (i18n) support for parsing keywords
+  - `groupHeaderPatterns`: customizable words/patterns for group headers
+  - `rangeSeparators`: customizable range separator words/patterns (e.g., "bis", "oder", "à")
+  - `descriptionStripPrefixes`: customizable prefix words/patterns to strip from descriptions
+  - `trailingQuantityContext`: customizable context words indicating trailing quantities
+- [#46] `includeMeta` option to include source metadata (`sourceText` and `sourceIndex`) on each parsed ingredient
+- [#46] Deprecated legacy exports (`fors`, `forsRegEx`, `rangeSeparatorWords`, `rangeSeparatorRegEx`, `ofs`, `ofRegEx`, `froms`, `fromRegEx`) in favor of new configurable defaults and regex builders
 
 ## [v2.0.1] - 2026-01-30
 
@@ -209,6 +218,7 @@ N/A
 [#34]: https://github.com/jakeboone02/parse-ingredient/pull/34
 [#37]: https://github.com/jakeboone02/parse-ingredient/pull/37
 [#40]: https://github.com/jakeboone02/parse-ingredient/pull/40
+[#46]: https://github.com/jakeboone02/parse-ingredient/pull/46
 
 <!-- Release comparison links -->
 

README.md

@@ -80,6 +80,8 @@ In the browser, all exports including the `parseIngredient` function are availab
 
 ## Usage
 
+The `parseIngredient` function accepts a string (with newline-separated ingredients) or an array of strings (one ingredient per element).
+
 ```js
 import { parseIngredient } from 'parse-ingredient';
 
@@ -223,6 +225,41 @@ parseIngredient('2 large eggs', { ignoreUOMs: ['large'] });
 // ]
 ```
 
+### `includeMeta`
+
+When `true`, each ingredient object will include a `meta` property containing source metadata:
+
+- `sourceText`: The original text of the ingredient line before parsing.
+- `sourceIndex`: The zero-based line number in the original input (accounts for empty lines).
+
+```js
+parseIngredient('1 cup flour\n\n2 tbsp sugar', { includeMeta: true });
+// [
+//   {
+//     quantity: 1,
+//     quantity2: null,
+//     unitOfMeasure: 'cup',
+//     unitOfMeasureID: 'cup',
+//     description: 'flour',
+//     isGroupHeader: false,
+//     meta: { sourceText: '1 cup flour', sourceIndex: 0 },
+//   },
+//   {
+//     quantity: 2,
+//     quantity2: null,
+//     unitOfMeasure: 'tbsp',
+//     unitOfMeasureID: 'tablespoon',
+//     description: 'sugar',
+//     isGroupHeader: false,
+//     meta: { sourceText: '2 tbsp sugar', sourceIndex: 2 },
+//   },
+// ]
+```
+
+## Internationalization (i18n)
+
+The library supports parsing ingredients in multiple languages through configurable keyword options. While unit names can be localized using `additionalUOMs`, the following options allow localization of parsing keywords and quantities.
+
 ### `decimalSeparator`
 
 The character used as a decimal separator in numeric quantities. Use `','` for European-style decimal commas (e.g., `'1,5'` for 1.5). Defaults to `'.'`.
@@ -241,6 +278,102 @@ parseIngredient('1,5 cups sugar', { decimalSeparator: ',' });
 // ]
 ```
 
+### `groupHeaderPatterns`
+
+Patterns to identify group headers (e.g., "For the icing:"). Strings are treated as prefix patterns matched at the start of the line followed by whitespace. RegExp patterns are used as-is for more complex matching. Defaults to `['For']`.
+
+```js
+// German group headers
+parseIngredient('Für den Teig:\n2 cups flour', {
+  groupHeaderPatterns: ['For', 'Für'],
+});
+// [
+//   { description: 'Für den Teig:', isGroupHeader: true, ... },
+//   { quantity: 2, unitOfMeasure: 'cups', description: 'flour', ... }
+// ]
+
+// French with regex pattern (matches "Pour la", "Pour le", "Pour un", etc.)
+parseIngredient('Pour la pâte:', {
+  groupHeaderPatterns: ['For', /^Pour\s/iu],
+});
+```
+
+### `rangeSeparators`
+
+Words or patterns to identify ranges between quantities (e.g., "1 to 2", "1 or 2"). Dash characters (-, –, —) are always recognized. Defaults to `['to', 'or']`.
+
+```js
+// German range separators
+parseIngredient('1 bis 2 cups flour', {
+  rangeSeparators: ['to', 'or', 'bis', 'oder'],
+});
+// [{ quantity: 1, quantity2: 2, ... }]
+
+// French range separator
+parseIngredient('2 à 3 cups sugar', {
+  rangeSeparators: ['to', 'or', 'à', 'ou'],
+});
+```
+
+### `descriptionStripPrefixes`
+
+Words or patterns to strip from the beginning of ingredient descriptions. Commonly used to remove "of" from phrases like "1 cup of sugar". Strings are matched as whole words followed by whitespace. RegExp patterns are used as-is, which is useful for languages with contractions or elisions. Defaults to `['of']`.
+
+> **Note:** This option is only applied when `allowLeadingOf` is `false` (the default). If `allowLeadingOf` is `true`, prefix stripping is disabled entirely and this option is ignored.
+
+```js
+// Spanish "de" stripping
+parseIngredient('2 tazas de azúcar', {
+  descriptionStripPrefixes: ['of', 'de'],
+});
+// [{ description: 'azúcar', ... }]
+
+// French with regex patterns for elisions/contractions
+parseIngredient("2 tasses d'huile", {
+  descriptionStripPrefixes: [/de\s+la\s+/iu, /de\s+l'/iu, /d'/iu, 'de'],
+});
+// [{ description: 'huile', ... }]
+```
+
+### `trailingQuantityContext`
+
+Words that indicate a trailing quantity extraction context, used to identify patterns like "Juice of 3 lemons". Defaults to `['from', 'of']`.
+
+```js
+// German context word
+parseIngredient('Saft von 3 Zitronen', {
+  trailingQuantityContext: ['from', 'of', 'von'],
+});
+// [{ quantity: 3, description: 'Saft von Zitronen', ... }]
+```
+
+### Full i18n Example (German)
+
+```js
+parseIngredient(
+  `Für den Kuchen:
+2 bis 3 Tassen Mehl
+1 Tasse Zucker`,
+  {
+    groupHeaderPatterns: ['For', 'Für'],
+    rangeSeparators: ['to', 'or', 'bis', 'oder'],
+    decimalSeparator: ',',
+    additionalUOMs: {
+      tasse: {
+        short: 'T',
+        plural: 'Tassen',
+        alternates: ['Tasse'],
+      },
+    },
+  }
+);
+// [
+//   { description: 'Für den Kuchen:', isGroupHeader: true, ... },
+//   { quantity: 2, quantity2: 3, unitOfMeasure: 'Tassen', description: 'Mehl', ... },
+//   { quantity: 1, unitOfMeasure: 'Tasse', description: 'Zucker', ... }
+// ]
+```
+
 ## Unit Conversion
 
 ### `convertUnit`

src/constants.ts

@@ -1,6 +1,84 @@
 import { numericRegex } from 'numeric-quantity';
 import { ParseIngredientOptions, UnitOfMeasureDefinitions } from './types';
 
+// --- i18n Utilities ---
+
+/**
+ * Escapes special regex characters in a string.
+ */
+export const escapeRegex = (str: string): string => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * Builds a regex that matches any of the given patterns at the start of a string,
+ * followed by whitespace. Strings are escaped and treated as literal prefixes.
+ * RegExp patterns have their source extracted and combined.
+ */
+export const buildPrefixPatternRegex = (patterns: (string | RegExp)[]): RegExp => {
+  const parts = patterns.map(p =>
+    p instanceof RegExp ? `(?:${p.source})` : `(?:${escapeRegex(p)})\\s`
+  );
+  return new RegExp(`^(?:${parts.join('|')})`, 'iu');
+};
+
+/**
+ * Builds a regex source string for range separators (dashes and word separators).
+ * Always includes dash characters (-, –, —), plus any custom word separators.
+ */
+export const buildRangeSeparatorSource = (words: (string | RegExp)[]): string => {
+  const wordParts = words.map(w =>
+    w instanceof RegExp ? `(?:${w.source})` : `(?:${escapeRegex(w)})`
+  );
+  // Always include dashes, then word separators followed by whitespace
+  return `(-|–|—|(?:${wordParts.join('|')})\\s)`;
+};
+
+/**
+ * Builds a regex that matches range separators at the start of a string.
+ */
+export const buildRangeSeparatorRegex = (words: (string | RegExp)[]): RegExp =>
+  new RegExp(`^${buildRangeSeparatorSource(words)}`, 'iu');
+
+/**
+ * Builds a regex that matches any of the given words or patterns at the start of a string.
+ * Strings are matched as whole words followed by whitespace.
+ * RegExp patterns are used as-is for more complex matching (e.g., French elisions).
+ */
+export const buildStripPrefixRegex = (patterns: (string | RegExp)[]): RegExp => {
+  const parts = patterns.map(p =>
+    p instanceof RegExp ? `(?:${p.source})` : `(?:${escapeRegex(p)})\\s+`
+  );
+  return new RegExp(`^(?:${parts.join('|')})`, 'iu');
+};
+
+/**
+ * Builds a regex that matches any of the given words at the end of a string,
+ * preceded by whitespace. Used for trailing quantity context like "from" or "of".
+ */
+export const buildTrailingContextRegex = (words: string[]): RegExp =>
+  new RegExp(`\\s+(?:${words.map(escapeRegex).join('|')})$`, 'iu');
+
+// --- Default i18n Values ---
+
+/**
+ * Default group header prefixes (e.g., "For the icing:").
+ */
+export const defaultGroupHeaderPatterns = ['For'] as const;
+
+/**
+ * Default range separator words (e.g., "1 to 2", "1 or 2").
+ */
+export const defaultRangeSeparators = ['or', 'to'] as const;
+
+/**
+ * Default words to strip from the beginning of descriptions.
+ */
+export const defaultDescriptionStripPrefixes = ['of'] as const;
+
+/**
+ * Default words that indicate trailing quantity context.
+ */
+export const defaultTrailingQuantityContext = ['from', 'of'] as const;
+
 /**
  * Default options for {@link parseIngredient}.
  */
@@ -10,26 +88,42 @@ export const defaultOptions: Required<ParseIngredientOptions> = {
   normalizeUOM: false,
   ignoreUOMs: [],
   decimalSeparator: '.',
+  groupHeaderPatterns: defaultGroupHeaderPatterns as unknown as string[],
+  rangeSeparators: defaultRangeSeparators as unknown as string[],
+  descriptionStripPrefixes: defaultDescriptionStripPrefixes as unknown as (string | RegExp)[],
+  trailingQuantityContext: defaultTrailingQuantityContext as unknown as string[],
+  includeMeta: false,
 } as const;
 
+// --- Legacy Exports (for backward compatibility) ---
+
 /**
- * List of "for" equivalents (for upcoming i18n support).
+ * List of "for" equivalents.
+ * @deprecated Use `defaultGroupHeaderPatterns` instead.
  */
-export const fors = ['For'] as const;
+export const fors: typeof defaultGroupHeaderPatterns = defaultGroupHeaderPatterns;
+
 /**
- * Regex to capture "for" equivalents (for upcoming i18n support).
+ * Regex to capture "for" equivalents.
+ * @deprecated Build dynamically using `buildPrefixPatternRegex(options.groupHeaderPatterns)`.
  */
-export const forsRegEx: RegExp = new RegExp(`^(?:${fors.join('|')})\\s`, 'iu');
+export const forsRegEx: RegExp = buildPrefixPatternRegex(
+  defaultGroupHeaderPatterns as unknown as string[]
+);
 
 /**
- * List of range separators (for upcoming i18n support).
+ * List of range separators.
+ * @deprecated Use `defaultRangeSeparators` instead.
  */
-export const rangeSeparatorWords = ['or', 'to'] as const;
-const rangeSeparatorRegExSource = `(-|–|—|(?:${rangeSeparatorWords.join('|')})\\s)`;
+export const rangeSeparatorWords: typeof defaultRangeSeparators = defaultRangeSeparators;
+
 /**
- * Regex to capture range separators (for upcoming i18n support).
+ * Regex to capture range separators.
+ * @deprecated Build dynamically using `buildRangeSeparatorRegex(options.rangeSeparators)`.
  */
-export const rangeSeparatorRegEx: RegExp = new RegExp(`^${rangeSeparatorRegExSource}`, 'iu');
+export const rangeSeparatorRegEx: RegExp = buildRangeSeparatorRegex(
+  defaultRangeSeparators as unknown as string[]
+);
 
 /**
  * Regex to capture the first word of a description, to see if it's a unit of measure.
@@ -39,31 +133,53 @@ export const firstWordRegEx: RegExp =
 
 const numericRegexAnywhere = numericRegex.source.replace('^', '').replace(/\$$/, '');
 
+/**
+ * Builds a regex to capture trailing quantity and unit of measure,
+ * using the provided range separator words.
+ */
+export const buildTrailingQuantityRegex = (rangeSeparators: (string | RegExp)[]): RegExp => {
+  const rangeSeparatorSource = buildRangeSeparatorSource(rangeSeparators);
+  return new RegExp(
+    `(,|:|-|–|—|x|⨯)?\\s*((${numericRegexAnywhere})\\s*(${rangeSeparatorSource}))?\\s*(${numericRegexAnywhere})\\s*(fl(?:uid)?(?:\\s+|-)(?:oz|ounces?)|[\\p{L}\\p{N}_]+)?$`,
+    'iu'
+  );
+};
+
 /**
  * Regex to capture trailing quantity and unit of measure.
+ * @deprecated Build dynamically using `buildTrailingQuantityRegex(options.rangeSeparators)`.
  */
-export const trailingQuantityRegEx: RegExp = new RegExp(
-  `(,|:|-|–|—|x|⨯)?\\s*((${numericRegexAnywhere})\\s*(${rangeSeparatorRegExSource}))?\\s*(${numericRegexAnywhere})\\s*(fl(?:uid)?(?:\\s+|-)(?:oz|ounces?)|[\\p{L}\\p{N}_]+)?$`,
-  'iu'
+export const trailingQuantityRegEx: RegExp = buildTrailingQuantityRegex(
+  defaultRangeSeparators as unknown as string[]
 );
 
 /**
- * List of "of" equivalents (for upcoming i18n support).
+ * List of "of" equivalents.
+ * @deprecated Use `defaultDescriptionStripPrefixes` instead.
  */
-export const ofs = ['of'] as const;
+export const ofs: typeof defaultDescriptionStripPrefixes = defaultDescriptionStripPrefixes;
+
 /**
- * Regex to capture "of" equivalents at the beginning of a string (for upcoming i18n support).
+ * Regex to capture "of" equivalents at the beginning of a string.
+ * @deprecated Build dynamically using `buildStripPrefixRegex(options.descriptionStripPrefixes)`.
  */
-export const ofRegEx: RegExp = new RegExp(`^(?:${ofs.join('|')})\\s+`, 'iu');
+export const ofRegEx: RegExp = buildStripPrefixRegex(
+  defaultDescriptionStripPrefixes as unknown as string[]
+);
 
 /**
- * List of "from" equivalents (for upcoming i18n support).
+ * List of "from" equivalents.
+ * @deprecated Use `defaultTrailingQuantityContext` instead.
  */
-export const froms = ['from', 'of'] as const;
+export const froms: typeof defaultTrailingQuantityContext = defaultTrailingQuantityContext;
+
 /**
- * Regex to capture "from" equivalents at the end of a string (for upcoming i18n support).
+ * Regex to capture "from" equivalents at the end of a string.
+ * @deprecated Build dynamically using `buildTrailingContextRegex(options.trailingQuantityContext)`.
  */
-export const fromRegEx: RegExp = new RegExp(`\\s+(?:${froms.join('|')})$`, 'iu');
+export const fromRegEx: RegExp = buildTrailingContextRegex(
+  defaultTrailingQuantityContext as unknown as string[]
+);
 
 /**
  * Default unit of measure specifications.