Capitalize React concepts in docs

[rickhanlonii]

Summary

We should be capitalizing proper React concepts in the docs. This was flagged by @samselikoff here and I took a first pass at correct Effects, Hooks, and Transitions in https://github.com/reactjs/react.dev/pull/6712.

Remaining items

The remaining items are:

• [ ] Components (In progress: https://github.com/reactjs/react.dev/pull/6717)
• [ ] State (In progress: https://github.com/reactjs/react.dev/pull/6720)
• [ ] Actions
• [ ] Context (In progress: https://github.com/reactjs/react.dev/pull/6718)
• [ ] Suspense
• [ ] Error Boundaries (In Progress: https://github.com/reactjs/react.dev/pull/6719)
• [ ] ... more?

Submitting a PR

• Please do not ask to take an item, just submit a PR. If multiple people submit the same PR, I'll add co-author credit to the commit.

• Only submit one PR per concept

• When you submit a PR, please try and cover all usages in all the docs, on all pages excluding the blog and community pages.

• Avoid fixing one or two instances and favor full coverage to minimize the number of PRs and reviews.

Note that headings like {/* usestate */} must stay lower case, so a find and replace won't work.

Style Guide

• Capitalize React-specific concepts: Capitalize the names of React concepts and features when referring to them specifically.
• Lowercase all others: Use lowercase when these words are used in a general context or referring to their general computing or programming meaning.

Guidelines for Specific Terms

Components

• Capitalize when referring to React Components
  • ❌ Incorrect: "functional components are a core concept in React."
  • ✅ Correct: "Functional Components are a core concept in React."
• Use lowercase when discussing components in a general programming or descriptive sense
  • ❌ Incorrect: "Components should manage their own State."
  • ✅ Correct: "components should manage their own state."

State

• Capitalize when discussing React State in the context of the React system
  • ❌ Incorrect: "Create dynamic and interactive Components with state."
  • ✅ Correct: "Create dynamic and interactive Components with State."
• Use lowercase for the general concept of state
  • ❌ Incorrect: "When a component's State changes, it re-renders."
  • ✅ Correct: "When a component's state changes, it re-renders."

Effects

• Capitalize when referring to Effects used via hooks like useEffect
  • ❌ Incorrect: "Use effects to perform side effects in function components."
  • ✅ Correct: "Use Effects to perform side effects in function components."
• Use lowercase for general references to effects or side effects in programming
  • ❌ Incorrect: "Effects let you perform side Effects in function components."
  • ✅ Correct: "Effects let you perform side effects in Function Components."

Transitions

• Capitalize when discussing the specific Transition feature ("use Transitions to defer updates").
  • ❌ Incorrect: "use transitions to defer updates"
  • ✅ Correct: "use Transitions to defer updates"
• Use lowercase when referring to the general concept of transitions in UI/UX ("transition animations").
  • ❌ Incorrect: You can also add a CSS Transition to delay dimming
  • ✅ Correct: You can also add a CSS transition to delay dimming

Context

• Capitalize when discussing the specific Context feature ("use Context to share data").
  • ❌ Incorrect: "use context to share data between components"
  • ✅ Correct: "use Context to share data between Components"
• Use lowercase when the word "context" refers to the general concept of context (understand the context)
  • ❌ Incorrect: "understand the Context it's running in"
  • ✅ Correct: "understand the context it's running in"

[dlitsman]

Curious if Props should also be capitalized similar to State/Context?

Also, updated my pull requests to remove blog/* changes

[smikitky]

I would like to remind you that most languages that do not belong to the Indo-European language family don't have the concept of uppercase/lowercase to begin with. Many languages in the world are unicase.

I agree with introducing visual distinctions between terms like "state" and "State" or "(side) effect" and "Effect", since these have actually confused developers for many years. However, I hope you will proceed with caution when continuously recycling existing common nouns and introducing new capitalized React concepts, such as "Action" or "Offscreen".

In many languages, including my own, it's often challenging to come up with separate translations for "action" and "Action" without causing confusion among readers. Sometimes we just give up on the translation altogether and denote React-specific concepts as Action, in English, but this is not ideal.

[kassens]

@smikitky this must be seen as a style guide for English where these rules are often used. It also doesn't even apply in German which I know because all nouns like Action would always be capitalized. Other translations should develop their own style guide. It's good to think about the style and do It consistently for one language so it's matching the norm of that language and "Action" for example (if translated) would have 1 translation for the language.

[smikitky]

Before doing this, I suggest contacting the maintainers of the active languages and obtaining their agreement. This is mostly a simple "Find & Replace" task for English authors, but for the maintainers of other languages, this would mean manually resolving literally thousands of Git conflicts across dozens of files. (An automated script won't help unless you've made a language fork 100% up-to-date with the main repo.) If this happens without prior notice, I wouldn't be surprised if the maintainers of one or two languages will give up on their contribution because of this. This would also cause conflicts in a large portion of the existing pull requests on the English repo.

By the way, do you know of any other project that capitalizes all unique keywords like this? Why do we need to make such a drastic change now? I understand "side effect" and "Effect" was a reasonable compromise, but I doubt other terms like "props", "key", "ref", "hook" and "context" have caused noticeable confusion. If the intent behind this change is to introduce more pairs like "action" and "Action" in the future, then perhaps it's this naming approach itself that needs reconsideration.

[rickhanlonii]

@smikitky translations can reject the upstream changes that updates the capitalization, the words are the same so the current word can stay in place without a breaking change. Then, if languages want to denote "concepts" separately like we're doing here, then they can handle that async.

One thing we can do to make the task easier is merge all of the changes into a feature branch, and land all the renames in a single commit. Then there's just one commit to ignore conflicts in.

[smikitky]

@rickhanlonii Thank you, I found the git merge -X theirs option which can ignore all incoming and conflicting changes. So we can escape from the bot workflow for this part, and merge the commit manually without breaking the merge history. Please make sure the commit only contains changes regarding uppercase/lowercase.

[dlitsman]

Do we still plan to merge this one? @rickhanlonii

[smikitky]

Even if we set aside the burden on translators, is it really worth capitalizing every primitive concept? While I understand it's natural to capitalize brand names and important architectural names such as "App Router" and "React Server Components", it's not common practice in English to capitalize primitive concepts like "prop", "ref", "component", "key" or "state". Similarly, programmers in general don't capitalize "function", "array", "expression", "variable", "argument" and so on just because they have special meanings in programming. Aside from "Effect", I fear that unconditional capitalization would make the docs look awkward and do more harm than good.

Even if the docs conversion is successfully completed once, it would be challenging to ensure future authors and reviewers will follow the new rules every time new text is added. It's also doubtful that people who engage in educating and promoting React outside your team will respect the new rules in the future.

By the way, this recent article uses uppercase Hook and this recent blog post uses lowercase hook. Why? Personally, I don't see any reason to capitalize it, because "hook" is a unique term that leaves no room for misunderstanding, and can now safely be considered a primitive in the React ecosystem.