fix(comments): align locale resource names, improve i18n usage

[rexxars]

Description

Apologies for bigger PR than anticipated. I will outline the main changes I have done below:

• This started off as wanting to remove the comments. prefix from comments locale resources - since there is already an explicit comments namespace, the extra layer is unnecessary. It means the full resource names are actually comments:comments.some-resource-key. This should be done asap, as we want to get locale packs up to date and include comment resources in their translations.

• The comments that are located above resources were lacking some clarity on what their purpose was, which makes it hard for translators to actually figure out what to translate them as without diving deep into the code. I made an attempt of improving the ones that I thought were the hardest to reason about.

• There was a Strong component passed down to a few resources, which looked to take children, but actually always rendered the field name. In these cases we should either:

  1. Let the users utilize simple tags such as <strong> directly (do not need to pass a component, but do need to use the <Translate> component), and pass the field name as a title (I went for this approach)
  2. Pass something specific, like <FieldName/>

• The list of user names is indeed non-trivial to render in an internationalized way. If you add resource strings that are "words"/"parts of a sentence", such as and, it is usually a sign that the approach does not necessarily fit in all languages. For lists, this plays out like this:

  • US English: A, B, and C
  • UK English: A, B and C
  • Norwegian: A, B og C
  • Japanese: A、B、C

  Because of these differences, we introduced a useListFormat hook, which exposes the browsers' underlying Intl.ListFormat API with the users' chosen locale. This can be used to either format lists straight up: useListFormat().format(['A', 'B', 'C']), or by using the formatToParts, we can get access to each "token" - either an element (A) or a literal (,, and).

  I refactored the code that displays use names to utilize this API, removing the need for and and resource. Additionally, I changed the logic around the You handling. Capitalization is not the same in all languages, so I found it cleaner to refer to it as "leading" (eg you are the first user) or not. It somehow still doesn't feel too clean, but at least this allows people to customize the strings as before. I also decided to pass it the actual username, should some language prefer/mandate that you do not refer to "You" but rather an actual name. Altered the story for this component to more easily be able to test this.

• Found a difference between "fieldName" and "fieldTitle", so decided to unify these and simply name them "field".

• The timestamps that we show for creation date did not use the localization API. I introduced the useDateFormat hook and made these match the old timestamps in style/length, but still be locale aware. Also used a <time> element with the full iso timestamp for a potential improvement to screen readers etc.

• There was a warning being printed about a t prop being passed to a button element - I tracked it down to a cloneElement call, and removed it.

• Found a placeholder that was not yet localized, added a resource for it

• Grouped together and renamed resources to be more in line with the rest of the Sanity codebase

• Sorted some imports and added type-only declarations in some locations

What to review

Please thoroughly test the comments feature for any broken strings. Glossing over the HTML for aria-labels that are broken is probably wise too. Note that since the studio defaults to en-US, you'll now have oxford commas (A, B, and C instead of A, B and C) - this is intentional and in line with the Intl APIs.

Testing

No new surfaces introduced, so no change in testing here.
I did add a few expansions to the reactions story to more easily test the "you" logic.

Notes for release

• Made timestamps in comments aware of the current studio locale

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
performance-studio	❌ Failed (Inspect)			Feb 6, 2024 2:42pm
test-studio	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Feb 6, 2024 2:42pm

1 Ignored Deployment

Name	Status	Preview	Comments	Updated (UTC)
studio-workshop	⬜️ Ignored (Inspect)	Visit Preview		Feb 6, 2024 2:42pm

[github-actions]

No changes to documentation

[github-actions]

Component Testing Report Updated Feb 5, 2024 6:26 PM (UTC)

File	Status	Duration	Passed	Skipped	Failed
comments/CommentInput.spec.tsx	✅ Passed (Inspect)	34s	15	0	0
formBuilder/ArrayInput.spec.tsx	✅ Passed (Inspect)	6s	3	0	0
formBuilder/inputs/PortableText/Annotations.spec.tsx	✅ Passed (Inspect)	12s	3	0	0
formBuilder/inputs/PortableText/copyPaste/CopyPaste.spec.tsx	✅ Passed (Inspect)	13s	4	2	0
formBuilder/inputs/PortableText/Decorators.spec.tsx	✅ Passed (Inspect)	13s	6	0	0
formBuilder/inputs/PortableText/FocusTracking.spec.tsx	✅ Passed (Inspect)	33s	15	0	0
formBuilder/inputs/PortableText/Input.spec.tsx	✅ Passed (Inspect)	19s	9	0	0
formBuilder/inputs/PortableText/ObjectBlock.spec.tsx	❌ Failed (Inspect)	1m 7s	17	0	1
formBuilder/inputs/PortableText/Styles.spec.tsx	✅ Passed (Inspect)	13s	6	0	0
formBuilder/inputs/PortableText/Toolbar.spec.tsx	✅ Passed (Inspect)	20s	9	0	0

[ninaandal]

Thank you for this cleanup Espen! This makes a lot of sense (and is a lot more clean), so this is noted for next time 👍

I think it could be very beneficial to add some of your comments in the description to the internal docs. I used those docs a lot when working with this and maybe it can prevent some similar mistakes to happen

[hermanwikner]

It is a bit unfortunate that the separator can end up on its own line (see image). Is there any way to prevent this from happening?

[rexxars]

I think it could be very beneficial to add some of your comments in the description to the Notion docs. I used those docs a lot when working with this and maybe it can prevent some similar mistakes to happen

Thanks for pointing that out @ninaandal - will add it.

When there are two names displayed – there is no space between the first name and the "and" string (see image). I am not sure why this is happening

This is caused by the span not rendering leading/trailing whitespace. I have added white-space: break-spaces to work around this.

It is a bit unfortunate that the separator can end up on its own line (see image). Is there any way to prevent this from happening?

Thanks for catching this and the above issue @hermanwikner !

28118e0 addresses them both by introducing a smarter logic based on the segmentation:

While iterating over the elements, checks whether or not the next element is a literal (, and , , and similar strings) and if so, whether or not it starts with a whitespace.

1. If it starts with a whitespace character, we allow it to be rendered as-is, as it has a natural "breaking point"
2. If it does not start with a whitespace character (, and ), it is rendered alongside the current element (user name), in a "text group" (inline block) which makes the browser treat it as a unit and prevents it from breaking on commas as far as I can tell.

If you still see issues with incorrect wrapping of literals, we could use white-space: pre/pre-wrap instead.

[hermanwikner]

Works great – thanks @rexxars!