Skip to content

Upgrading to 4.0

nepali_utils 4.0 is a near-total rewrite. Most of the API is still there, but almost every class has changed. Some changes break the build, so the compiler will point you to them. Others compile fine and return different values. This guide covers both kinds.

Changes that compile but behave differently are marked with Silent. Changes the compiler will report are marked with Compile error.

Section titled “Recommended: migrate with an AI coding agent”

The quickest way to upgrade is to let a coding agent do it. Copy the prompt below into Claude Code, Codex, Antigravity, Cursor or any other coding agent, and run it from the root of your project. The prompt contains every rule from this guide, so the agent doesn’t need web access.

The rest of this page explains each change, in case you prefer to migrate by hand or want to review what the agent did.

Migration prompt
Migrate this Dart/Flutter project from nepali_utils 3.x to nepali_utils 4.0.
4.0 is a near-total rewrite. Some changes break the build; others still compile but
return different values ("silent changes"). Handle both. The full guide is at
https://nepali-utils.sarbagyastha.com.np/migration/v4/ — read it if you can browse,
but the rules below are complete.
140 collapsed lines
## Workflow
1. Find every usage. Search all Dart files (lib/, test/, bin/, integration_test/,
example/, packages/*) for: nepali_utils, NepaliUtils, NepaliDateTime,
toNepaliDateTime, NepaliDateFormat, NepaliNumberFormat, NepaliMoment,
NepaliUnicode, Language.
2. Update pubspec.yaml: `environment: sdk: ^3.13.0` and `nepali_utils: ^4.0.0`.
Run `dart pub get` (or `flutter pub get`). If the SDK constraint can't be raised,
stop and tell me.
3. Fix all compile errors using the rules below.
4. Review every silent-change site below and decide what the code meant.
5. Run `dart analyze` (or `flutter analyze`) and the tests. Fix what this migration broke.
6. Only touch code related to this migration. Don't reformat or refactor anything else.
## Compile-breaking changes
- Imports: deep imports of `package:nepali_utils/src/...` no longer work. Use only
`import 'package:nepali_utils/nepali_utils.dart';`.
- Every public class is now `final` (NepaliUtils, Preeti and Devanagari are
`abstract final` with static members only). Classes that extend or implement
NepaliDateTime, NepaliDateFormat, NepaliNumberFormat, NepaliMoment or NepaliUnicode
must use composition instead. NepaliDateTime still implements DateTime.
- NepaliUtils is no longer a singleton:
- `NepaliUtils(lang)` → `NepaliUtils.defaultLanguage = lang`
- `NepaliUtils().language` → `NepaliUtils.currentLanguage`
- `NepaliUtils().language = lang` → `NepaliUtils.defaultLanguage = lang`
- New: `NepaliUtils.withLanguage(lang, () => ...)` for a scoped override.
- Formatters read the language when they are created, not when they format.
If code changes the language and then reuses a formatter created earlier,
recreate the formatter (or pass the language explicitly).
- NepaliNumberFormat: the constructor with named arguments is removed. Map as follows:
- `NepaliNumberFormat()` → `NepaliNumberFormat.decimalPattern()`
- `NepaliNumberFormat(language: lang)` → `NepaliNumberFormat.decimalPattern(lang)`
- `decimalDigits: n` → `NepaliNumberFormat.decimalPatternDigits(decimalDigits: n)`
- `isMonetory: true, symbol: 'Rs.'` → `NepaliNumberFormat.simpleCurrency()`
or `NepaliNumberFormat.currency(symbol: 'Rs.')`
- `symbolOnLeft: false` → `.currency(symbol: 'Rs.', customPattern: '#,##,##0.00 ¤')`
- `spaceBetweenAmountAndSymbol: false` → `.currency(symbol: 'Rs.', customPattern: '¤#,##,##0.00')`
- `inWords: true` → `NepaliNumberFormat.words(useDigits: true)` to keep the old
`1 lakh 23 thousand` style, or `NepaliNumberFormat.words()` for real words
(`one lakh twenty-three thousand`). Ask me if it is unclear which is wanted.
- `inWords: true, isMonetory: true` → `NepaliNumberFormat.words(currency: true)`
- `delimiter: ''` → `.copyWith(groupSeparator: '')`
- `includeDecimalIfZero: false` → `.copyWith(includeDecimalIfZero: false)`
- `format(null)` used to return `''`; `format` now takes a non-null `Object`.
Handle null at the call site, e.g. `value == null ? '' : f.format(value)`.
- NepaliMoment: the `showToday` parameter is removed (it had no effect) — delete it.
`NepaliMoment.fromAD` / `fromBS` still work. For "Today at …" use
`NepaliMoment().calendar(date)`; for "today" use
`NepaliMoment().formatUnit(0, MomentUnit.day, numeric: false)`.
- NepaliUnicode is now an instance `Converter<String, String>`:
- `NepaliUnicode.convert(text)` → `const NepaliUnicode().convert(text)`
- `NepaliUnicode.convert(text, live: true)` → `const NepaliUnicode().convertLive(text)`
- `toNepaliDateTimeFromInstant()` (only on the develop branch) is removed →
`toNepaliDateTime().toNepalTime()`.
## Silent changes (compile fine, behave differently) — check every site
1. `NepaliDateTime.now()` now returns the device's LOCAL time (like DateTime.now()),
not Nepal time. If the code means "now / today in Nepal" (calendar UI, today's BS
date, business logic for Nepal), replace it with `NepaliDateTime.nepalNow()`.
Keep `now()` only when local time is really intended. Default to `nepalNow()` and
list each decision in your report.
2. `DateTime.toNepaliDateTime()` (and `NepaliDateTime.fromDateTime`) now KEEPS the
time zone. In 3.x the result was always shifted to Nepal time. For UTC values
(API/server timestamps, `DateTime.parse('...Z')`, `DateTime.utc(...)`,
`.toUtc()`, Firestore timestamps) append `.toNepalTime()` wherever Nepal time is
expected. This affects devices in Nepal too.
3. NepaliDateTime is now instant-based:
- `toDateTime()` returns the same instant (UTC stays UTC). In 3.x it returned a
local DateTime with the same wall-clock fields.
- `toUtc()` now works (it used to throw); `toLocal()` now converts (it used to
return `this`); new `toNepalTime()`, `isNepalTime`.
- `timeZoneName` / `timeZoneOffset` now reflect the real zone (were always
Nepal Time / +5:45).
- `NepaliDateTime(...)` creates a LOCAL value. Use `NepaliDateTime.nepal(...)` for
Nepal time or `NepaliDateTime.utc(...)` for UTC.
- `==` / `hashCode` now compare instant + zone (before: identity). Code relying on
two equal dates being unequal, or on Set/Map duplicates, behaves differently.
- Out-of-range fields roll over like DateTime (`NepaliDateTime(2080, 1, 35)` is
2080-02-04). Years outside 1969–2250 BS throw RangeError in all builds.
- `NepaliDateTime.parse` honours `Z` and offsets like DateTime.parse (3.x ignored
them): no suffix → local, `Z` → UTC, `+05:45` → Nepal time.
4. NepaliDateFormat now follows intl's DateFormat:
- Named skeleton constructors (`yM`, `yMd`, `yMEd`, `yMMMd`, `jm`, `H`, …) and
skeleton strings like `NepaliDateFormat('yMd')` now produce intl `en`/`ne`
layouts, e.g. `yMd` was `2076/08/05` and is now `8/5/2076` (English) or
`२०७६-०८-०५` (Nepali). Where the exact old output matters (stored strings,
API payloads, file names, tests), use an explicit pattern such as
`NepaliDateFormat('y/MM/dd')`.
- Pattern letters changed: `E`/`EE`/`EEE` are all `Thu` (use `EEEE` for
`Thursday`, `EEEEE` for `T`); `G`/`GG`/`GGG` are all `BS` (`GGGG` is
`Bikram Sambat`); English `a`/`aa` give `PM`; the colloquial month name moved
from `MMMMM` to `MMMMMM`; `S` now prints at least 3 digits.
- Bug fixes: `Hm()`, `m()`, `ms()`, `h` at midnight and `hh` padding now give the
correct values.
- Formatters are immutable: `addPattern` and `add_*()` return a NEW formatter.
Code like `f.add_jm(); f.format(d);` must become `f = f.add_jm();` or chaining.
- English time skeletons put a narrow no-break space (U+202F) before AM/PM.
5. NepaliNumberFormat:
- Numbers are rounded half away from zero instead of truncated (`2.999` with 2
digits → `3.00`, was `2.99`).
- `decimalPattern()` shows up to 3 fraction digits and drops trailing zeros
(`1234.5` → `1,234.5`, was `1,234.50`). Use `decimalPatternDigits` for fixed digits.
- `currency()` / `simpleCurrency()` always show 2 decimals (`Rs. 1,234.00` for an
int, was `Rs. 1,234`). Pass `decimalDigits: 0` to keep the old output.
- `currency()` without `symbol` uses `NPR`; `simpleCurrency()` uses `Rs.` / `रु.`.
- A no-break space (U+00A0) separates the symbol and the amount.
- Nepali "rupees" is now spelled `रुपैयाँ` (was `रुपैया`).
- `words(useDigits: true).format(100000)` gives `1 lakh` (zero groups omitted).
6. NepaliMoment wording and thresholds now match moment.js, e.g. `few moment ago` →
`a few seconds ago`, `one minute ago` → `a minute ago`, `5 minute ago` →
`5 minutes ago`, `about an hour ago` → `an hour ago`, 22 hours → `a day ago`,
26 days → `a month ago`, 320 days → `a year ago`, `3 days from now` → `in 3 days`.
Nepali drops `लगभग` and follows the same thresholds. The language comes from the
`language` argument or `NepaliUtils.currentLanguage` at creation time.
7. NepaliUnicode leaves text inside `{}` unchanged and removes the braces
(`mero naam {Sarbagya} ho` → `मेरो नाम Sarbagya हो`). If input can contain a
literal `{`, escape it as `{{}`. Spelling fixes in the classic style
(`kamal` → `कमल्`, `chhoraa` → `छोरा`, `gyaan` → `ज्ञान्`, `singha` → `सिंह`);
any whitespace now drops a halant; `kchy` no longer gives `क्ष`.
## Tests
Tests that compare strings will fail because of the changes above (date skeletons,
U+202F before AM/PM, U+00A0 in currency, rounding, fraction digits, NepaliMoment
wording, NepaliUnicode output). Update an expected value only after confirming the
new output is the intended 4.0 behaviour. Do not weaken or delete assertions.
Use ` ` / ` ` escapes in expected strings so the special spaces are visible.
## Report
When done, give me:
- the files you changed;
- every silent-change site (file:line), what you chose and why — especially each
`now()` vs `nepalNow()`, each `toNepaliDateTime()` with or without `.toNepalTime()`,
and each place where a skeleton or number output changed;
- anything you weren't sure about and left for me to decide;
- the analyzer and test results.
  1. Upgrade the SDK. 4.0 requires Dart ^3.13.0.

    pubspec.yaml
    environment:
    sdk: ^3.13.0
    dependencies:
    nepali_utils: ^4.0.0
  2. Import only package:nepali_utils/nepali_utils.dart. The src/ files have moved, and every public class is now final.

  3. Set the default language through the static API. Replace NepaliUtils(lang) with NepaliUtils.defaultLanguage = lang.

  4. Check every NepaliDateTime.now() call. Use NepaliDateTime.nepalNow() wherever you meant “the current time in Nepal”.

  5. Check every toNepaliDateTime() call on a UTC or server timestamp. Append .toNepalTime() if you need Nepal time.

  6. Rewrite NepaliNumberFormat(...) calls with named arguments. Use the named constructors: decimalPattern, decimalPatternDigits, currency, simpleCurrency and words.

  7. Make NepaliUnicode an instance. Write const NepaliUnicode().convert(text).

  8. Update tests that compare strings. Date skeletons, currency spacing, NepaliMoment wording and number rounding all give different output now.

Compile error

The package uses primary constructors, dot shorthands, records, patterns and extension types, so it needs Dart 3.13 or later. Pub won’t resolve 4.0 on older SDKs.

Compile error

Every public class is now final. This includes NepaliDateTime, NepaliDateFormat, NepaliNumberFormat, NepaliMoment and NepaliUnicode. NepaliUtils, Preeti and Devanagari are abstract final and contain only static members. You can no longer extend or implement these classes. If you wrapped them, use composition instead.

NepaliDateTime still implements DateTime, so you can pass it anywhere a DateTime is expected.

Compile error

The lib/src/ folder has been reorganised. For example, src/nepali_date_time.dart is now src/date_time/nepali_date_time.dart. Deep imports break, so import the library instead:

import 'package:nepali_utils/nepali_utils.dart';

NepaliUtils was a singleton that stored a mutable language. It now works like intl’s Intl.defaultLocale and Intl.withLocale, and it only has static members.

3.x 4.0
NepaliUtils(Language.nepali) NepaliUtils.defaultLanguage = Language.nepali
NepaliUtils().language NepaliUtils.currentLanguage
NepaliUtils().language = lang NepaliUtils.defaultLanguage = lang
(none) NepaliUtils.withLanguage(lang, () => ...)
NepaliUtils(Language.nepali);
final isNepali = NepaliUtils().language == Language.nepali;

Language also converts to and from locale identifiers: Language.parse('ne_NP'), Language.tryParse, Language.fromLocale, localeName and toLanguageTag(). See Language.

NepaliDateTime is now based on an instant, just like DateTime. It stores microsecondsSinceEpoch plus a time zone, and shows its fields in one of three zones: local, UTC or Nepal Time.

In 3.x, a NepaliDateTime was a set of fields that were always assumed to be in Nepal Time. This change fixes a lot of incorrect behaviour on devices outside Nepal and with UTC timestamps. It also changes results that used to “just work” in Nepal.

Silent
// Always Nepal time, whatever the device's time zone.
final today = NepaliDateTime.now();

On a device set to Nepal Time, both calls show the same fields. nepalNow() is still the correct choice when you mean Nepal time.

Silent
final utc = DateTime.utc(2024, 1, 1);
print(utc.toNepaliDateTime()); // 2080-09-16 05:45:00.000

The unreleased toNepaliDateTimeFromInstant() (only on the develop branch) has been removed. Use toNepaliDateTime().toNepalTime() instead.

NepaliDateTime.fromDateTime(dateTime) is no longer deprecated. It does the same thing as toNepaliDateTime().

Member 3.x 4.0
toDateTime() A local DateTime with the same wall-clock fields The same instant: UTC values give a UTC DateTime, others give a local one
toUtc() Threw UnimplementedError Converts to UTC
toLocal() Returned this Converts to local time
toNepalTime() (none) Converts to Nepal Time
isUtc / isNepalTime Always false / (none) Reflects the zone
timeZoneName / timeZoneOffset Always Nepal Time / +5:45 The real zone: NPT / 5:45 for Nepal Time, UTC, or the local zone
final nepal = NepaliDateTime.nepal(2081, 1, 1, 10);
print(nepal.toUtc()); // 2081-01-01 04:15:00.000Z
print(nepal.timeZoneName); // NPT
Silent

== and hashCode now compare the instant and the time zone. Before, they compared identity, so two equal dates were never ==. Values used as Map keys or in a Set now deduplicate as you would expect.

NepaliDateTime(2080, 1, 1) == NepaliDateTime(2080, 1, 1); // 3.x: false, 4.0: true

difference, isBefore, isAfter, isAtSameMomentAs and compareTo now accept any DateTime, not only another NepaliDateTime.

Silent

Out-of-range components roll over like they do in DateTime. Years outside 1969–2250 BS throw a RangeError. Before, they only failed an assert, which does nothing in release builds.

print(NepaliDateTime(2080, 1, 35)); // 2080-02-04 00:00:00.000 (3.x kept day 35)
print(NepaliDateTime(2080, 13, 1)); // 2081-01-01 00:00:00.000
NepaliDateTime(2300); // throws RangeError

The constructors are now factories. NepaliDateTime(...) creates a local value. Use NepaliDateTime.utc(...) or NepaliDateTime.nepal(...) for the other zones.

Silent

NepaliDateTime.parse now follows DateTime.parse. In 3.x, a Z or offset suffix was accepted but ignored.

Input 3.x 4.0
2080-01-01T10:00:00 10:00, Nepal Time 10:00 local
2080-01-01T10:00:00Z 10:00, Nepal Time 10:00 UTC
2080-01-01T10:00:00+05:45 10:00, Nepal Time 10:00 Nepal Time
2080-01-01T10:00:00+01:00 10:00, Nepal Time 09:00 UTC
  • New constructors: NepaliDateTime.utc, .nepal, .nepalNow, .fromMicrosecondsSinceEpoch and .fromMillisecondsSinceEpoch.
  • New members: copyWith, toNepalTime and isNepalTime.
  • New constants: NepaliDateTime.sunday … saturday and baishakh … chaitra.
  • format(pattern), mergeTime, totalDays, totalDaysInYear, add, subtract and tryParse work as before.

NepaliDateFormat now follows package:intl’s DateFormat exactly. It is an immutable final class. Its format accepts any DateTime and keeps that value’s time zone.

NepaliDateFormat.yMd().format(DateTime(2019, 11, 21)); // 8/5/2076
NepaliDateFormat(); // no pattern: uses 'yMMMMd jms'
Silent

The named constructors are now intl’s skeletons. English uses intl’s en layouts and Nepali uses its ne layouts. A skeleton name passed to the default constructor, as in NepaliDateFormat('yMd'), is resolved the same way. The table shows Mangsir 5, 2076, 9:04 PM:

Constructor 3.x 4.0 English 4.0 Nepali
yM 2076/08 8/2076 २०७६-०८
yMd 2076/08/05 8/5/2076 २०७६-०८-०५
yMEd Thu, 2076/08/05 Thu, 8/5/2076 २०७६-०८-०५, बिहि
yMMMd मं ५, २०७६ (Nepali) Marg 5, 2076 २०७६ मं ५
jm बेलुकी ९:०४ (Nepali) 9:04 PM २१:०४ (24-hour)
H (at 9:04 AM) 9 09 ०९

If you need the 3.x layout, pass the old pattern explicitly. For example, NepaliDateFormat('y/MM/dd') gives 2076/08/05.

Silent
Pattern 3.x 4.0
E / EE / EEE T / Thu / Thursday Thu (all three)
EEEE / EEEEE not supported (printed as is) Thursday / T
G / GG / GGG BS / B.S. / Bikram Sambat BS (all three); GGGG is Bikram Sambat
a / aa (English) pm / PM PM
MMMMM Marga (colloquial) M (narrow); the colloquial name is now MMMMMM
S / SS 1 / 12 123 (at least 3 digits)
QQQ / QQQQ (Nepali) Q3 / 3rd quarter तेस्रो त्रैमासिक; Q digits are Devanagari
Constructor or pattern 3.x 4.0
NepaliDateFormat.Hm() 21:08 (minutes showed the month: HH:MM) 21:04 (HH:mm)
NepaliDateFormat.m() 9 (showed the hour) 4 (m)
NepaliDateFormat.ms() 9:04 (hh:mm) 04:00 (mm:ss)
h at midnight 0 12
hh from 1 PM to 9 PM 9 (not padded) 09

Skeletons also respect the default language set through NepaliUtils.

NepaliDateFormat can’t be changed after you create it. addPattern and the add_*() methods return a new formatter:

final format = NepaliDateFormat.yMd().add_jm();
format.format(NepaliDateTime(2076, 8, 5, 21, 4)); // 8/5/2076 9:04 PM

4.0 also adds:

  • The pattern letters L, c, D, K, k, z/v (NPT, UTC; zzzz is Nepal Time) and Z (+0545).
  • The EEEEE, jmv, jmz, jv and jz constructors.
  • Skeleton constants such as NepaliDateFormat.YEAR_MONTH_DAY.

See Date formatting.

NepaliNumberFormat now follows package:intl’s NumberFormat and is an immutable final class. The old constructor with named arguments has been removed. Compile error

3.x 4.0
NepaliNumberFormat() NepaliNumberFormat.decimalPattern() (up to 3 fraction digits), or NepaliNumberFormat([pattern])
NepaliNumberFormat(language: lang) NepaliNumberFormat.decimalPattern(lang)
NepaliNumberFormat(decimalDigits: 2) NepaliNumberFormat.decimalPatternDigits(decimalDigits: 2)
isMonetory: true, symbol: 'Rs.' NepaliNumberFormat.simpleCurrency() (Rs. 1,234.00) or .currency(symbol: 'Rs.')
symbolOnLeft: false .currency(symbol: 'Rs.', customPattern: '#,##,##0.00 ¤')
spaceBetweenAmountAndSymbol: false .currency(symbol: 'Rs.', customPattern: '¤#,##,##0.00')
inWords: true NepaliNumberFormat.words(), which now gives real words. Use words(useDigits: true) for the old 1 lakh 23 thousand style
inWords: true, isMonetory: true NepaliNumberFormat.words(currency: true)
delimiter: '' .copyWith(groupSeparator: '')
includeDecimalIfZero: false .copyWith(includeDecimalIfZero: false)
format<T>(T? number), null gave '' format(Object number); passing null is a compile error
NepaliNumberFormat(decimalDigits: 2).format(1234567.891);
// 12,34,567.89
NepaliNumberFormat(isMonetory: true, symbol: 'Rs.').format(1234);
// Rs. 1,234
NepaliNumberFormat(isMonetory: true, symbol: 'Rs.', symbolOnLeft: false)
.format(1234);
// 1,234 Rs.
NepaliNumberFormat(inWords: true).format(123456);
// 1 lakh 23 thousand 4 hundred 56
NepaliNumberFormat(inWords: true, isMonetory: true, language: Language.nepali)
.format(123.45);
// १ सय २३ रुपैया ४५ पैसा
NepaliNumberFormat(delimiter: '').format(1234567);
// 1234567
  • Default fraction digits. In 3.x, decimalDigits defaulted to 0 for an int and 2 for a double or String, with trailing zeros kept. decimalPattern() shows up to 3 fraction digits and drops trailing zeros. 1234.5 gives 1,234.5 (it was 1,234.50), and 1234567.891 gives 12,34,567.891. Use decimalPatternDigits(decimalDigits: n) for a fixed number of digits.
  • Currency always has 2 decimals. currency() and simpleCurrency() give Rs. 1,234.00 for an int, where 3.x gave Rs. 1,234. Pass decimalDigits: 0 to keep the old output.
  • Currency spacing. Currency patterns are taken from intl’s ne locale, with a no-break space (U+00A0) between the symbol and the amount. A test that compares against 'Rs. 1,234.00' with an ordinary space will fail.
  • Currency defaults. currency() uses NPR when you don’t pass a symbol. simpleCurrency() uses Rs. / रु.. In 3.x, isMonetory without a symbol showed no symbol.
  • Spelling. In Nepali, rupees is now spelled रुपैयाँ (was रुपैया).
  • Words without zero groups. words(useDigits: true).format(100000) gives 1 lakh. 3.x gave 1 lakh 00 thousand 0 hundred 00.

4.0 also adds percent and compact formats (12.3L, 12.3 lakh), custom patterns, parse/tryParse with Devanagari digits, significant digits, and full support for negatives, BigInt and long numeric strings. See Number formatting.

NepaliMoment is now an immutable formatter in the style of moment.js. fromBS and fromAD still work as static shorthands, but the showToday parameter has been removed. It had no effect. Compile error

NepaliMoment.fromAD(date, referenceDate: now);
NepaliMoment.fromBS(date, showToday: true);
Silent
Span 3.x English 4.0 English 3.x Nepali 4.0 Nepali
10 seconds ago few moment ago a few seconds ago केही क्षण पहिले केही क्षण पहिले
1 minute ago one minute ago a minute ago एक मिनेट पहिले एक मिनेट पहिले
5 minutes ago 5 minute ago 5 minutes ago ५ मिनेट पहिले ५ मिनेट पहिले
50 minutes ago about an hour ago an hour ago लगभग एक घण्टा पहिले एक घण्टा पहिले
22 hours ago 22 hours ago a day ago २२ घण्टा पहिले एक दिन पहिले
30 hours ago one day ago a day ago एक दिन पहिले एक दिन पहिले
26 days ago 26 days ago a month ago २६ दिन पहिले एक महिना पहिले
45 days ago about a month ago a month ago लगभग एक महिना पहिले एक महिना पहिले
60 days ago 2 month ago 2 months ago २ महिना पहिले २ महिना पहिले
320 days ago 11 month ago a year ago ११ महिना पहिले एक वर्ष पहिले
350 days ago 12 month ago a year ago १२ महिना पहिले एक वर्ष पहिले
400 days ago about one year ago a year ago लगभग एक वर्ष पहिले एक वर्ष पहिले
800 days ago 2 year ago 2 years ago २ वर्ष पहिले २ वर्ष पहिले
in 3 days 3 days from now in 3 days ३ दिन पछि ३ दिन पछि

The thresholds now match moment.js:

Elapsed time Output
under 45 seconds a few seconds
45 to 89 seconds a minute
90 seconds to 44 minutes 2 minutes … 44 minutes
45 to 89 minutes an hour
90 minutes to 21 hours 2 hours … 21 hours
22 to 35 hours a day
36 hours to 25 days 2 days … 25 days
26 to 45 days a month
46 to 319 days 2 months … 10 months
320 to 547 days a year
548 days or more 2 years …

NepaliMoment(useWeeks: true) adds weeks (3 weeks ago) for spans between 7 days and a month. NepaliMoment(style: MomentStyle.short) abbreviates the units (3 hr. ago / ३ घ. पहिले).

The language now comes from the language argument, or from NepaliUtils.currentLanguage when the formatter is created. See Relative time for formatDuration, formatUnit and calendar.

NepaliUnicode used to be a class with static methods. It is now an immutable Converter<String, String>. Compile error

3.x 4.0
NepaliUnicode.convert(text) const NepaliUnicode().convert(text)
NepaliUnicode.convert(text, live: true) const NepaliUnicode().convertLive(text), or just convert. Devanagari followed by romanized text is joined either way
NepaliUnicode.convert('kamal'); // कयल्
NepaliUnicode.convert('mero naam {Sarbagya} ho'); // {षर्बज्ञ्} converted too
NepaliUnicode.convert(text, live: true);

The default classic style keeps the 3.x rules, with these fixes:

Input 3.x 4.0
sayau स​यौ (with a zero width space) सयौ
kamal कयल् कमल्
chhoraa छ्ोरा छोरा
gyaan ज्ञ्ान् ज्ञान्
singha सिहं सिंह

Also:

  • Any whitespace now drops a halant, not only a space.
  • kchy no longer gives क्ष.
  • Digits are still converted to Devanagari (25 → २५). The new nepaliDigits: false option keeps ASCII digits.

4.0 also adds the google, mppRomanized and mppTraditional styles, toRoman (the reverse conversion) and stream support. See Nepali Unicode.

These modules are new in 4.0, so there is nothing to migrate:

  • Preeti and Devanagari: Preeti.toUnicode / Preeti.fromUnicode convert legacy Preeti-font text. Devanagari adds digit conversion, detection and akshara splitting.
  • Measurement units: NepaliArea (ropani-aana-paisa-daam, bigha-kattha-dhur), NepaliWeight (tola-lal, dharni-ser) and NepaliVolume (muri-pathi-mana). They support conversion, formatting, parsing and arithmetic.
  • Phone numbers: NepaliPhoneNumber validates mobile and landline numbers, detects the operator (Nepal Telecom, Ncell, …) or the district, formats as national, international or E.164, and finds numbers in text.
  • Nepali Unicode: Google and MPP input styles, toRoman, {English} escapes and stream transforms.
  • Relative time: formatDuration, formatUnit (yesterday / हिजो), calendar, short style and weeks.
  • Number formatting: compact (12.3L, १२.३ लाख), percent, custom patterns, parsing and real number-to-words.
  • Date formatting: time-zone letters, add_* chaining and skeleton constants.
  • Nepali date and time: time zones (utc, nepal, nepalNow), copyWith, and constant-time AD ↔ BS conversion that is about 16× faster.

For the complete list, see the changelog.