locale => lang

docs/components/format-bytes.md

@@ -101,24 +101,24 @@ const App = () => (
 
 ### Localization
 
-Use the `locale` attribute to set the number formatting locale.
+Use the `lang` attribute to set the number formatting locale.
 
 ```html preview
-<sl-format-bytes value="12" locale="de"></sl-format-bytes><br>
-<sl-format-bytes value="1200" locale="de"></sl-format-bytes><br>
-<sl-format-bytes value="1200000" locale="de"></sl-format-bytes><br>
-<sl-format-bytes value="1200000000" locale="de"></sl-format-bytes>
+<sl-format-bytes value="12" lang="de"></sl-format-bytes><br>
+<sl-format-bytes value="1200" lang="de"></sl-format-bytes><br>
+<sl-format-bytes value="1200000" lang="de"></sl-format-bytes><br>
+<sl-format-bytes value="1200000000" lang="de"></sl-format-bytes>
 ```
 
 ```jsx react
 import { SlFormatBytes } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlFormatBytes value="12" locale="de" /><br />
-    <SlFormatBytes value="1200" locale="de" /><br />
-    <SlFormatBytes value="1200000" locale="de" /><br />
-    <SlFormatBytes value="1200000000" locale="de" />
+    <SlFormatBytes value="12" lang="de" /><br />
+    <SlFormatBytes value="1200" lang="de" /><br />
+    <SlFormatBytes value="1200000" lang="de" /><br />
+    <SlFormatBytes value="1200000000" lang="de" />
   </>
 );
 ```

docs/components/format-date.md

@@ -97,22 +97,22 @@ const App = () => (
 
 ### Localization
 
-Use the `locale` attribute to set the date/time formatting locale.
+Use the `lang` attribute to set the date/time formatting locale.
 
 ```html preview
-English: <sl-format-date locale="en"></sl-format-date><br>
-French: <sl-format-date locale="fr"></sl-format-date><br>
-Russian: <sl-format-date locale="ru"></sl-format-date>
+English: <sl-format-date lang="en"></sl-format-date><br>
+French: <sl-format-date lang="fr"></sl-format-date><br>
+Russian: <sl-format-date lang="ru"></sl-format-date>
 ```
 
 ```jsx react
 import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    English: <SlFormatDate locale="en" /><br />
-    French: <SlFormatDate locale="fr" /><br />
-    Russian: <SlFormatDate locale="ru" />
+    English: <SlFormatDate lang="en" /><br />
+    French: <SlFormatDate lang="fr" /><br />
+    Russian: <SlFormatDate lang="ru" />
   </>
 );
 ```

docs/components/format-number.md

@@ -75,48 +75,48 @@ const App = () => (
 
 ### Localization
 
-Use the `locale` attribute to set the number formatting locale.
+Use the `lang` attribute to set the number formatting locale.
 
 ```html preview
-English: <sl-format-number value="2000" locale="en" minimum-fraction-digits="2"></sl-format-number><br>
-German: <sl-format-number value="2000" locale="de" minimum-fraction-digits="2"></sl-format-number><br>
-Russian: <sl-format-number value="2000" locale="ru" minimum-fraction-digits="2"></sl-format-number>
+English: <sl-format-number value="2000" lang="en" minimum-fraction-digits="2"></sl-format-number><br>
+German: <sl-format-number value="2000" lang="de" minimum-fraction-digits="2"></sl-format-number><br>
+Russian: <sl-format-number value="2000" lang="ru" minimum-fraction-digits="2"></sl-format-number>
 ```
 
 ```jsx react
 import { SlFormatNumber } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    English: <SlFormatNumber value="2000" locale="en" minimum-fraction-digits="2" /><br />
-    German: <SlFormatNumber value="2000" locale="de" minimum-fraction-digits="2" /><br />
-    Russian: <SlFormatNumber value="2000" locale="ru" minimum-fraction-digits="2" />
+    English: <SlFormatNumber value="2000" lang="en" minimum-fraction-digits="2" /><br />
+    German: <SlFormatNumber value="2000" lang="de" minimum-fraction-digits="2" /><br />
+    Russian: <SlFormatNumber value="2000" lang="ru" minimum-fraction-digits="2" />
   </>
 );
 ```
 
 ### Currency
 
-To format a number as a monetary value, set the `type` attribute to `currency` and set the `currency` attribute to the desired ISO 4217 currency code. You should also specify `locale` to ensure the the number is formatted correctly for the target locale.
+To format a number as a monetary value, set the `type` attribute to `currency` and set the `currency` attribute to the desired ISO 4217 currency code. You should also specify `lang` to ensure the the number is formatted correctly for the target locale.
 
 ```html preview
-<sl-format-number type="currency" currency="USD" value="2000" locale="en-US"></sl-format-number><br>
-<sl-format-number type="currency" currency="GBP" value="2000" locale="en-GB"></sl-format-number><br>
-<sl-format-number type="currency" currency="EUR" value="2000" locale="de"></sl-format-number><br>
-<sl-format-number type="currency" currency="RUB" value="2000" locale="ru"></sl-format-number><br>
-<sl-format-number type="currency" currency="CNY" value="2000" locale="zh-cn"></sl-format-number>
+<sl-format-number type="currency" currency="USD" value="2000" lang="en-US"></sl-format-number><br>
+<sl-format-number type="currency" currency="GBP" value="2000" lang="en-GB"></sl-format-number><br>
+<sl-format-number type="currency" currency="EUR" value="2000" lang="de"></sl-format-number><br>
+<sl-format-number type="currency" currency="RUB" value="2000" lang="ru"></sl-format-number><br>
+<sl-format-number type="currency" currency="CNY" value="2000" lang="zh-cn"></sl-format-number>
 ```
 
 ```jsx react
 import { SlFormatNumber } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlFormatNumber type="currency" currency="USD" value="2000" locale="en-US" /><br />
-    <SlFormatNumber type="currency" currency="GBP" value="2000" locale="en-GB" /><br />
-    <SlFormatNumber type="currency" currency="EUR" value="2000" locale="de" /><br />
-    <SlFormatNumber type="currency" currency="RUB" value="2000" locale="ru" /><br />
-    <SlFormatNumber type="currency" currency="CNY" value="2000" locale="zh-cn" />
+    <SlFormatNumber type="currency" currency="USD" value="2000" lang="en-US" /><br />
+    <SlFormatNumber type="currency" currency="GBP" value="2000" lang="en-GB" /><br />
+    <SlFormatNumber type="currency" currency="EUR" value="2000" lang="de" /><br />
+    <SlFormatNumber type="currency" currency="RUB" value="2000" lang="ru" /><br />
+    <SlFormatNumber type="currency" currency="CNY" value="2000" lang="zh-cn" />
   </>
 );
 ```

docs/components/relative-time.md

@@ -78,26 +78,26 @@ const App = () => (
 
 ### Localization
 
-Use the `locale` attribute to set the desired locale.
+Use the `lang` attribute to set the desired locale.
 
 ```html preview
-English: <sl-relative-time date="2020-07-15T09:17:00-04:00" locale="en-US"></sl-relative-time><br>
-Chinese: <sl-relative-time date="2020-07-15T09:17:00-04:00" locale="zh-CN"></sl-relative-time><br>
-German: <sl-relative-time date="2020-07-15T09:17:00-04:00" locale="de"></sl-relative-time><br>
-Greek: <sl-relative-time date="2020-07-15T09:17:00-04:00" locale="el"></sl-relative-time><br>
-Russian: <sl-relative-time date="2020-07-15T09:17:00-04:00" locale="ru"></sl-relative-time>
+English: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="en-US"></sl-relative-time><br>
+Chinese: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="zh-CN"></sl-relative-time><br>
+German: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="de"></sl-relative-time><br>
+Greek: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="el"></sl-relative-time><br>
+Russian: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="ru"></sl-relative-time>
 ```
 
 ```jsx react
 import { SlRelativeTime } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    English: <SlRelativeTime date="2020-07-15T09:17:00-04:00" locale="en-US" /><br />
-    Chinese: <SlRelativeTime date="2020-07-15T09:17:00-04:00" locale="zh-CN" /><br />
-    German: <SlRelativeTime date="2020-07-15T09:17:00-04:00" locale="de" /><br />
-    Greek: <SlRelativeTime date="2020-07-15T09:17:00-04:00" locale="el" /><br />
-    Russian: <SlRelativeTime date="2020-07-15T09:17:00-04:00" locale="ru" />
+    English: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="en-US" /><br />
+    Chinese: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="zh-CN" /><br />
+    German: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="de" /><br />
+    Greek: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="el" /><br />
+    Russian: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="ru" />
   </>
 );
 ```

docs/resources/changelog.md

@@ -8,6 +8,7 @@ _During the beta period, these restrictions may be relaxed in the event of a mis
 
 ## Next
 
+- 🚨 BREAKING: changed the `locale` attribute to `lang` in `<sl-format-bytes>`, `<sl-format-date>`, `<sl-format-number>`, and `<sl-relative-time>` to be consistent with how localization will be handled
 - CodePen examples will now open in light or dark depending on your current preference
 - Fixed a bug where tag names weren't being generated in `vscode.html-custom-data.json` [#593](https://github.com/shoelace-style/shoelace/pull/593)
 - Fixed a bug in `<sl-tooltip>` where the tooltip wouldn't reposition when content changed

src/components/format-bytes/format-bytes.ts

@@ -15,12 +15,12 @@ export default class SlFormatBytes extends LitElement {
   @property() unit: 'bytes' | 'bits' = 'bytes';
 
   /** The locale to use when formatting the number. */
-  @property() locale: string;
+  @property() lang: string;
 
   render() {
     return formatBytes(this.value, {
       unit: this.unit,
-      locale: this.locale
+      lang: this.lang
     });
   }
 }

src/components/format-date/format-date.ts

@@ -11,7 +11,7 @@ export default class SlFormatDate extends LitElement {
   @property() date: Date | string = new Date();
 
   /** The locale to use when formatting the date/time. */
-  @property() locale: string;
+  @property() lang: string;
 
   /** The format for displaying the weekday. */
   @property() weekday: 'narrow' | 'short' | 'long';
@@ -55,7 +55,7 @@ export default class SlFormatDate extends LitElement {
       return;
     }
 
-    return new Intl.DateTimeFormat(this.locale, {
+    return new Intl.DateTimeFormat(this.lang, {
       weekday: this.weekday,
       era: this.era,
       year: this.year,

src/components/format-number/format-number.ts

@@ -11,7 +11,7 @@ export default class SlFormatNumber extends LitElement {
   @property({ type: Number }) value = 0;
 
   /** The locale to use when formatting the number. */
-  @property() locale: string;
+  @property() lang: string;
 
   /** The formatting style to use. */
   @property() type: 'currency' | 'decimal' | 'percent' = 'decimal';
@@ -45,7 +45,7 @@ export default class SlFormatNumber extends LitElement {
       return '';
     }
 
-    return new Intl.NumberFormat(this.locale, {
+    return new Intl.NumberFormat(this.lang, {
       style: this.type,
       currency: this.currency,
       currencyDisplay: this.currencyDisplay,

src/components/relative-time/relative-time.ts

@@ -18,7 +18,7 @@ export default class SlRelativeTime extends LitElement {
   @property() date: Date | string;
 
   /** The locale to use when formatting the number. */
-  @property() locale: string;
+  @property() lang: string;
 
   /** The formatting style to use. */
   @property() format: 'long' | 'short' | 'narrow' = 'long';
@@ -38,7 +38,7 @@ export default class SlRelativeTime extends LitElement {
   }
 
   @watch('date')
-  @watch('locale')
+  @watch('lang')
   @watch('format')
   @watch('numeric')
   @watch('sync')
@@ -65,7 +65,7 @@ export default class SlRelativeTime extends LitElement {
     const { unit, value } = availableUnits.find(unit => Math.abs(diff) < unit.max) as any;
 
     this.isoTime = date.toISOString();
-    this.titleTime = new Intl.DateTimeFormat(this.locale, {
+    this.titleTime = new Intl.DateTimeFormat(this.lang, {
       month: 'long',
       year: 'numeric',
       day: 'numeric',
@@ -74,7 +74,7 @@ export default class SlRelativeTime extends LitElement {
       timeZoneName: 'short'
     }).format(date);
 
-    this.relativeTime = new Intl.RelativeTimeFormat(this.locale, {
+    this.relativeTime = new Intl.RelativeTimeFormat(this.lang, {
       numeric: this.numeric,
       style: this.format
     }).format(Math.round(diff / value), unit);

src/internal/number.ts

@@ -5,7 +5,7 @@ export function formatBytes(bytes: number, options: FormatBytesOptions) {
   options = Object.assign(
     {
       unit: 'bytes',
-      locale: undefined
+      lang: undefined
     },
     options
   );
@@ -20,13 +20,13 @@ export function formatBytes(bytes: number, options: FormatBytesOptions) {
 
   const i = Math.min(Math.floor(Math.log10(bytes) / 3), units.length - 1);
   const num = Number((bytes / Math.pow(1000, i)).toPrecision(3));
-  const numString = num.toLocaleString(options.locale);
+  const numString = num.toLocaleString(options.lang);
   const prefix = isNegative ? '-' : '';
 
   return `${prefix}${numString} ${units[i]}`;
 }
 
 interface FormatBytesOptions {
   unit?: 'bytes' | 'bits';
-  locale?: string;
+  lang?: string;
 }