From 29375f4750576d6fed3fec3a607b1de57a8a7f13 Mon Sep 17 00:00:00 2001 From: Greg Slepak Date: Wed, 4 Oct 2023 10:25:19 -0700 Subject: [PATCH] Update Style-Guide.md Added `User-facing Strings Guide` --- docs/Style-Guide.md | 37 +++++++++++++++++++++++++++++++++++-- 1 file changed, 35 insertions(+), 2 deletions(-) diff --git a/docs/Style-Guide.md b/docs/Style-Guide.md index a84a067ede..8b0930930f 100644 --- a/docs/Style-Guide.md +++ b/docs/Style-Guide.md @@ -5,6 +5,7 @@ Please read all the sections below before writing a single line of code. - **[JavaScript Style Guide](#javascript-style-guide)** - **[Vue.js Style Guide](#vuejs-style-guide)** - **[CSS Style Guide](#css-style-guide)** +- **[User-facing Strings Guide](#user-facing-strings-guide)** - **[Accessibility Style Guide](#css-style-guide)** - **[Testing Style Guide](#testing-style-guide)** - **[Folder Structure Style Guide](#folder-structure-style-guide)** @@ -20,11 +21,14 @@ If you notice any file not properly linted by `standard`, this means there's a b _It is still on you to ensure your code conforms to the `standard` spec, whether or not the linter catches everything._ -### A Note On Classes: Avoid Them +### A Note On Classes: Avoid Them, Usually For this project we've made the very conscious decision to avoid Object Oriented Programming (OOP) as much as possible. Instead, we use [Selector-based Programming (SBP)](#sbp). What this means in practice is that where you'd normally see classes being used, we ask that you use SBP namespaces instead. We do this to avoid many of the pitfalls of OOP, and as a result our code ends up much simpler and more flexible than it otherwise would be. -You may of course use any necessary classes that others have created if it is unavoidable (for example, some of the built-in Node.js classes). However, avoid creating your own class definitions. In the entire project there is only a single class that we have declared that acts as an exception to this rule, and that is `GIMessage`. If there is no way to avoid creating a class definition, it may be permitted, but a strong case must be made first that there is no other way to do it. +You may of course use any necessary classes that others have created if it is unavoidable (for example, some of the built-in Node.js classes). However, avoid creating your own class definitions unless it makes sense when dealing with special types. Here are some examples of exceptions to the "avoid classes" rule: + +- `GIMessage`. This is an example of a very important type for wrapping and handling [`SPMessage`](https://shelterprotocol.net/en/spmessage/) types. +- `GIErrorUIRuntimeError`. A special error type for dealing with exceptions containing user-facing error strings when attempting to perform an action. ### See Also: "Embrace the SBP way of doing things" @@ -68,6 +72,35 @@ When writing the markup make sure its semantics are complete. For example, if th

Page details

``` + +## User-facing Strings Guide + +All user-facing strings must be wrapped in either an `L` function (in JavaScript), or using the `i18n` component (in HTML/Pug markup). + +It's OK to not wrap strings when writing `console.(debug|warn|error)` messages, because those are not user-facing. But anything the user sees in the UI must be wrapped in either an `L` function or `i18n` so that the [`strings`](https://github.com/okTurtles/group-income/blob/master/CONTRIBUTING.md#how-to-help-by-translating) utility can extract these strings and update related localization files. + +When creating these strings, we sometimes need to pass in a variable using braces (e.g. `{variable}`). Remember, translators are going to see these strings without any context, so it's important to provide them with context by using very clear names for variables that let the translator know what values the variable might take on. + +❌ Avoid choosing unclear variable names: + +``` +There was a problem with {nr} of your payments. +``` + +``` +Export your {type} payment history to .csv` +``` + +✅ Be clear what values the variable might take on: + +``` +There was a problem with {number} of your payments. +``` + +``` +Export your {sent_or_received} payment history to .csv` +``` + ## Accessibility Style Guide We are committed to ensuring digital accessibility for all people, including those with low vision, blindness, hearing impairments, cognitive impairments, motor impairments or situational disabilities. We are continually improving the user experience for everyone, and applying the relevant accessibility standards.