DOCSEARCHbyAlgolia
Submit Docs

vn-text Documentation

website·Indexed 29 days ago

https://vn-text.vercel.app/

A library for processing Vietnamese text, providing utilities to remove or check for diacritics and tone marks, and tools for creating Vietnamese-specific regular expressions.

Tokens
2K
Snippets
13
Records
18
Agent score
75%

What's inside vn-text

  1. Overview of @vn-utils/text library

    @vn-utils/text is a free, open-source library designed to help developers work more efficiently with the Vietnamese language. It is available on NPM and GitHub.

  2. Use createRegex with MongoDB and Mongoose

    The createRegex function from @vn-utils/text can be used directly in Mongoose queries if the environment supports JavaScript RegExp objects. If the specific MongoDB driver version does not support passing the RegExp object directly, use the .source and .flags properties of the generated regex within the $regex and $options operators.
    import { createRegex, CreateRegexOptions } from '@vn-utils/text';

const options: CreateRegexOptions = { /* your options */ };
const keywordRegex = createRegex('từ khoá tìm kiếm', options);

// Option 1: Direct RegExp object usage
const foundData = await model.find({ $or: [{ name: keywordRegex }] });

// Option 2: Using .source and .flags for environments that require explicit $regex operators
const foundDataAlt = await model.find({
    $or: [{ name: { $regex: keywordRegex.source, $options: keywordRegex.flags } }],
});

  3. Environment requirements for @vn-utils/text

    To use @vn-utils/text, ensure your environment meets the following requirements:

    • Node.js: Version 18.0 or higher (recommended).
    • Language Support: Compatible with both TypeScript and JavaScript.

  4. Install @vn-utils/text using a package manager

    Install the @vn-utils/text library using your preferred package manager via the command line.
    # Using NPM
npm install @vn-utils/text

# Using Yarn
yarn add @vn-utils/text

# Using PNPM
pnpm install @vn-utils/text

  5. Include @vn-utils/text in the browser via CDN

    Add the library to your HTML file using a script tag from jsDelivr. You can use the latest version or specify a particular version by replacing <VERSION> with the desired version number.
    <!-- Latest version -->
<script src="https://cdn.jsdelivr.net/npm/@vn-utils/text@latest/lib/bundle.js"></script>

<!-- Specific version -->
<script src="https://cdn.jsdelivr.net/npm/@vn-utils/text@<VERSION>/lib/bundle.js"></script>

  6. Handle Vietnamese diacritics in regex search

    When searching for Vietnamese text using regex, you must account for tone marks and diacritics. To find a specific word with a precise accent, use the exact character. To find all variations of a word regardless of the specific tone mark on a vowel, use a character class containing all possible accented versions of that vowel.
    // Search for the exact word 'học'
học

// Search for all variations of 'hoc' with different tone marks (o, ó, ọ, ỏ, õ)
h[oóọỏõ]c

  7. Import @vn-utils/text in Node.js

    The library supports both ES Modules (import) and CommonJS (require) syntax for Node.js environments.
    // ES Module
import * as vnUtilsText from '@vn-utils/text';

// CommonJS
const vnUtilsText = require('@vn-utils/text');

  8. Expand search results by combining createRegex with diacritic and tone removal

    To allow a search input to match Vietnamese text regardless of accents or diacritics, combine createRegex with removeDiacritics and removeTone. This ensures that a search term like 'Có dấu' matches variations such as 'Có dau day du' or 'Co dấu đầy du'.
    import { createRegex, removeDiacritics, removeTone } from '@vn-utils/text';

const data = ['Có dấu đầy đủ', 'Có dau day du', 'Co dấu đầy du', 'Có dáu day'];

// Strict match: only matches exact diacritics
data.filter((item) => createRegex('Có dấu').test(item)); // 1 result

// Broad match: removes both diacritics and tones to match all variations
data.filter((item) => createRegex(removeTone(removeDiacritics('Có dấu'))).test(item)); // 4 results

  9. Use @vn-utils/text in the browser

    When loaded via a script tag in the browser, the library is available globally through the vnUtilsText variable. You can use this variable directly or assign it to a custom variable.
    <script>
    // Direct usage
    vnUtilsText.hasTone('các dấu sắc huyền ngã hỏi nặng có tồn tại');

    // Assigning to a custom variable
    const customVariable = vnUtilsText;
    customVariable.hasTone('các dấu sắc huyền ngã hỏi nặng có tồn tại');
</script>

  10. Create a Vietnamese search regex with createRegex

    The createRegex function from @vn-utils/text generates a regular expression suitable for searching Vietnamese text. By default, it allows for flexible matching (e.g., matching 'Ha Noi' against 'Hà Nội').
    import { createRegex } from '@vn-utils/text';

const regex = createRegex('Tiếng Việt');
const data = ['Hà Nội', 'Hải Phòng'];

// Default behavior: accent-insensitive matching
data.filter((item) => createRegex('Ha Noi').test(item)); // [ 'Hà Nội' ]

  11. Reference Vietnamese tone marks and symbols

    Vietnamese uses the following tone marks to modify the meaning and pronunciation of words:

    1. Dấu sắc (´): High rising tone
    2. Dấu huyền (`): Low falling tone
    3. Dấu hỏi (̉): Dipping-rising tone
    4. Dấu ngã (˜): High rising glottalized tone
    5. Dấu nặng (.): Low falling constricted tone
    6. Không dấu ( ): Flat/neutral tone (no mark)

  12. Identify Vietnamese diacritics (dấu phụ)

    Vietnamese uses several diacritical marks (dấu phụ) to modify the sound of letters. These include:

    • Circumflex (Dấu mũ ˆ): used in â, ê, ô
    • Breve (Dấu trăng ˘): used in ă
    • Horn (Dấu móc ̛): used in ơ, ư
    • Bar (Dấu gạch ngang): used in đ