Required locale in setupIntl() (#1847)

* breaking: Removed setLocale() from intl service's constructor

* chore: Updated test assertions

* breaking, refactor: Simplified setupIntl()

* chore: Updated documentations

* chore: Added changeset

---------

Co-authored-by: ijlee2 <ijlee2@users.noreply.github.com>

.changeset/honest-ravens-vanish.md

@@ -0,0 +1,13 @@
+---
+"ember-intl": major
+"my-app-with-lazy-loaded-translations": patch
+"my-app-with-namespace-from-folders": patch
+"my-classic-app": patch
+"my-v1-engine": patch
+"my-v1-addon": patch
+"test-app-for-ember-intl": patch
+"docs-app-for-ember-intl": patch
+"my-app": patch
+---
+
+Required locale in setupIntl()

docs/ember-intl/app/templates/docs/guide/testing.md

@@ -3,44 +3,16 @@
 With `ember-intl`'s test helpers, you can check translations under various conditions easily.
 
 
-## setupIntl(hooks, [locale], [translations])
+## setupIntl(hooks, locale, [translations])
 
-In rendering and unit tests, you must add `setupIntl(hooks)` if they depend on `ember-intl`, e.g. you used the `{{t}}` helper in the template, or injected the `intl` service in the class.
+In rendering and unit tests, you should add `setupIntl()` if they depend on `ember-intl`, e.g. you used the `{{t}}` helper in the template, or injected the `intl` service in the class.
 
-You can also use `setupIntl()` to set the locale and stub translations. This setup runs as a part of the test module's `beforeEach` hook (e.g. before a component is rendered).
-
-In application tests, it's not necessary to call `setupIntl(hooks)`. The only time you might do this is to run a test module with a particular locale.
-
-
-### setupIntl(hooks)
-
-The syntax helps you check the default case. That is, what does the user see with the default locale and the translations as provided?
-
-```ts
-import { render } from '@ember/test-helpers';
-import { hbs } from 'ember-cli-htmlbars';
-import { setupIntl } from 'ember-intl/test-support';
-import { setupRenderingTest } from 'ember-qunit';
-import { module, test } from 'qunit';
-
-module('Integration | Component | hello', function (hooks) {
-  setupRenderingTest(hooks);
-  setupIntl(hooks);
-
-  test('it renders', async function (assert) {
-    await render(hbs`
-      <Hello @name="Zoey" />
-    `);
-
-    assert.dom('[data-test-message]').hasText('Hello, Zoey!');
-  });
-});
-```
+In application tests, it's not necessary to call `setupIntl()`. The only time you might do this is to run a test module with a particular locale.
 
 
 ### setupIntl(hooks, locale)
 
-The syntax helps you check the translations for a specific locale.
+The default syntax helps you check the translations for a specific locale.
 
 ```ts
 import { render } from '@ember/test-helpers';
@@ -64,39 +36,9 @@ module('Integration | Component | hello', function (hooks) {
 ```
 
 
-### setupIntl(hooks, translations)
-
-The syntax helps you stub the translations for the default locale.
-
-```ts
-import { render } from '@ember/test-helpers';
-import { hbs } from 'ember-cli-htmlbars';
-import { setupIntl } from 'ember-intl/test-support';
-import { setupRenderingTest } from 'ember-qunit';
-import { module, test } from 'qunit';
-
-module('Integration | Component | hello', function (hooks) {
-  setupRenderingTest(hooks);
-  setupIntl(hooks, {
-    hello: {
-      message: 'What\'s up, {name}?',
-    },
-  });
-
-  test('it renders', async function (assert) {
-    await render(hbs`
-      <Hello @name="Zoey" />
-    `);
-
-    assert.dom('[data-test-message]').hasText('What\'s up, Zoey?');
-  });
-});
-```
-
-
 ### setupIntl(hooks, locale, translations)
 
-The syntax helps you stub the translations for a specific locale.
+You can pass a translation object to stub the translations for a specific locale.
 
 ```ts
 import { render } from '@ember/test-helpers';
@@ -137,7 +79,7 @@ import { module, test } from 'qunit';
 
 module('Integration | Component | hello', function (hooks) {
   setupRenderingTest(hooks);
-  setupIntl(hooks);
+  setupIntl(hooks, 'en-us');
 
   test('it renders', async function (assert) {
     await render(hbs`
@@ -169,7 +111,7 @@ import { module, test } from 'qunit';
 
 module('Integration | Component | lazy-hello', function (hooks) {
   setupRenderingTest(hooks);
-  setupIntl(hooks);
+  setupIntl(hooks, 'en-us');
 
   test('Lazily loaded translations', async function (assert) {
     await render(hbs`
@@ -213,7 +155,7 @@ import { module, test } from 'qunit';
 
 module('Integration | Component | hello', function (hooks) {
   setupRenderingTest(hooks);
-  setupIntl(hooks);
+  setupIntl(hooks, 'en-us');
 
   test('it renders', async function (assert) {
     await render(hbs`

docs/ember-intl/app/templates/docs/migration/v7.md

@@ -20,7 +20,6 @@ This command has been removed, because the blueprints only addressed the simple
 How translation files are created will be left up to the end-developers.
 
 
-
 ### Removed `@intl` and `@t` macros
 
 The macros are a remnant of classic components and `ember-i18n`. They are not necessary in Octane, and prevent us from mainintaing and updating `ember-intl` more easily.
@@ -55,7 +54,7 @@ export default class MyComponent extends Component {
 After:
 
 ```ts
-import { inject as service, type Registry as Services } from '@ember/service';
+import { type Registry as Services, service } from '@ember/service';
 import Component from '@glimmer/component';
 
 export default class MyComponent extends Component {
@@ -93,7 +92,7 @@ Before:
 ```ts
 import Component from '@ember/component';
 import { computed } from '@ember/object';
-import { inject as service, type Registry as Services } from '@ember/service';
+import { type Registry as Services, service } from '@ember/service';
 
 export default class MyComponent extends Component {
   @service declare intl: Services['intl'];
@@ -120,7 +119,7 @@ export default class MyComponent extends Component {
 After:
 
 ```ts
-import { inject as service, type Registry as Services } from '@ember/service';
+import { type Registry as Services, service } from '@ember/service';
 import Component from '@glimmer/component';
 
 export default class MyComponent extends Component {
@@ -143,3 +142,63 @@ export default class MyComponent extends Component {
   }
 }
 ```
+
+
+### Required locale in test helpers
+
+Before `v7`, `ember-intl` allowed you to write `setupIntl(hooks)`. Your tests would somehow pass, even though you didn't specify under which locale the tests make sense.
+
+By favoring convenience and assuming that most apps target USA, we also created problems that became visible in `v6`:
+
+- `'en-us'` is always present in the `intl` service's `locales`, even when the app doesn't support the `en-us` locale.
+- `setupIntl()` needs to support 4 variations, increasing complexity and maintenance cost.
+
+To solve these issues and encourage writing code that is explicit, `setupIntl()` now requires you to specify the locale. To migrate code, use find-and-replace-all in your text editor.
+
+```diff
+module('Integration | Component | hello', function (hooks) {
+  setupRenderingTest(hooks);
+-   setupIntl(hooks);
++   setupIntl(hooks, 'en-us');
+
+  test('it renders', async function (assert) {
+    await render(hbs`
+      <Hello @name="Zoey" />
+    `);
+
+    assert.dom('[data-test-message]').hasText('Hello, Zoey!');
+  });
+});
+```
+
+Note, if you want to test multiple locales, you can use nested modules.
+
+```ts
+module('Integration | Component | hello', function (hooks) {
+  setupRenderingTest(hooks);
+
+  module('de-de', function (nestedHooks) {
+    setupIntl(nestedHooks, 'de-de');
+
+    test('it renders', async function (assert) {
+      await render(hbs`
+        <Hello @name="Zoey" />
+      `);
+
+      assert.dom('[data-test-message]').hasText('Hallo, Zoey!');
+    });
+  });
+
+  module('en-us', function (nestedHooks) {
+    setupIntl(nestedHooks, 'en-us');
+
+    test('it renders', async function (assert) {
+      await render(hbs`
+        <Hello @name="Zoey" />
+      `);
+
+      assert.dom('[data-test-message]').hasText('Hallo, Zoey!');
+    });
+  });
+});
+```

docs/ember-intl/tests/helpers/index.ts

@@ -24,7 +24,7 @@ function setupApplicationTest(hooks: NestedHooks, options?: SetupTestOptions) {
   // This is also a good place to call test setup functions coming
   // from other addons:
   //
-  // setupIntl(hooks); // ember-intl
+  // setupIntl(hooks, 'en-us'); // ember-intl
   // setupMirage(hooks); // ember-cli-mirage
 }
 

docs/ember-intl/tests/integration/components/locale-switcher-test.ts

@@ -6,7 +6,7 @@ import { module, test } from 'qunit';
 
 module('Integration | Component | locale-switcher', function (hooks) {
   setupRenderingTest(hooks);
-  setupIntl(hooks);
+  setupIntl(hooks, 'en-us');
 
   test('it renders', async function (assert) {
     await render(hbs`

docs/my-app-with-lazy-loaded-translations/tests/helpers/index.ts

@@ -24,7 +24,7 @@ function setupApplicationTest(hooks: NestedHooks, options?: SetupTestOptions) {
   // This is also a good place to call test setup functions coming
   // from other addons:
   //
-  // setupIntl(hooks); // ember-intl
+  // setupIntl(hooks, 'en-us'); // ember-intl
   // setupMirage(hooks); // ember-cli-mirage
 }
 

docs/my-app-with-lazy-loaded-translations/tests/integration/components/select-locale-test.ts

@@ -9,7 +9,7 @@ import { module, test } from 'qunit';
 
 module('Integration | Component | select-locale', function (hooks) {
   setupRenderingTest(hooks);
-  setupIntl(hooks);
+  setupIntl(hooks, 'en-us');
 
   test('it renders', async function (assert) {
     await render(hbs`

docs/my-app-with-namespace-from-folders/tests/helpers/index.ts

@@ -24,7 +24,7 @@ function setupApplicationTest(hooks: NestedHooks, options?: SetupTestOptions) {
   // This is also a good place to call test setup functions coming
   // from other addons:
   //
-  // setupIntl(hooks); // ember-intl
+  // setupIntl(hooks, 'en-us'); // ember-intl
   // setupMirage(hooks); // ember-cli-mirage
 }
 

docs/my-app-with-namespace-from-folders/tests/integration/components/select-locale-test.ts

@@ -9,7 +9,7 @@ import { module, test } from 'qunit';
 
 module('Integration | Component | select-locale', function (hooks) {
   setupRenderingTest(hooks);
-  setupIntl(hooks);
+  setupIntl(hooks, 'en-us');
 
   test('it renders', async function (assert) {
     await render(hbs`

docs/my-app/tests/helpers/index.ts

@@ -24,7 +24,7 @@ function setupApplicationTest(hooks: NestedHooks, options?: SetupTestOptions) {
   // This is also a good place to call test setup functions coming
   // from other addons:
   //
-  // setupIntl(hooks); // ember-intl
+  // setupIntl(hooks, 'en-us'); // ember-intl
   // setupMirage(hooks); // ember-cli-mirage
 }
 

docs/my-app/tests/integration/components/select-locale-test.ts

@@ -6,7 +6,7 @@ import { module, test } from 'qunit';
 
 module('Integration | Component | select-locale', function (hooks) {
   setupRenderingTest(hooks);
-  setupIntl(hooks);
+  setupIntl(hooks, 'en-us');
 
   test('it renders', async function (assert) {
     await render(hbs`

docs/my-classic-app/tests/helpers/index.ts

@@ -24,7 +24,7 @@ function setupApplicationTest(hooks: NestedHooks, options?: SetupTestOptions) {
   // This is also a good place to call test setup functions coming
   // from other addons:
   //
-  // setupIntl(hooks); // ember-intl
+  // setupIntl(hooks, 'en-us'); // ember-intl
   // setupMirage(hooks); // ember-cli-mirage
 }
 

docs/my-classic-app/tests/integration/components/select-locale-test.ts

@@ -6,7 +6,7 @@ import { module, test } from 'qunit';
 
 module('Integration | Component | select-locale', function (hooks) {
   setupRenderingTest(hooks);
-  setupIntl(hooks);
+  setupIntl(hooks, 'en-us');
 
   test('it renders', async function (assert) {
     await render(hbs`

docs/my-v1-addon/tests/helpers/index.ts

@@ -24,7 +24,7 @@ function setupApplicationTest(hooks: NestedHooks, options?: SetupTestOptions) {
   // This is also a good place to call test setup functions coming
   // from other addons:
   //
-  // setupIntl(hooks); // ember-intl
+  // setupIntl(hooks, 'en-us'); // ember-intl
   // setupMirage(hooks); // ember-cli-mirage
 }
 

docs/my-v1-engine/tests/helpers/index.ts

@@ -31,7 +31,7 @@ function setupApplicationTest(hooks: NestedHooks, options?: SetupTestOptions) {
   // This is also a good place to call test setup functions coming
   // from other addons:
   //
-  // setupIntl(hooks); // ember-intl
+  // setupIntl(hooks, 'en-us'); // ember-intl
   // setupMirage(hooks); // ember-cli-mirage
 }