p5.js: Friendly Errors i18n Book
Open source contribution to p5.js (javascript library for creative coding).
2021-2022.
2021-2022.
I wrote the internationalization (i18n) guidelines for making friendly errors with co-authors. Friendly errors are supplimentary error messages for p5.js library written in accessible language.
It is a collection of essays that discuss issues arising from the i18n process from the perspective of the destination culture (as opposed to the source culture where technology disperse out).
It is a collection of essays that discuss issues arising from the i18n process from the perspective of the destination culture (as opposed to the source culture where technology disperse out).
The co-writing project has grown out of the co-translation of the p5.js friendly error messages, collaborating with artists in Korea. I thank my co-writers 전유진(Youjin Jeon) and 염인화(Inhwa Yeom), as well as our editor 이지현(Jihyun Lee) for their time and valuable conversations.
Public release announcement flyer:
![]()
![]()
![]()
![]()
For an open-source project aspiring to reach international learners, it makes sense to try to reach people who are unable to navigate the English-dominant open-source platforms. For non-English speaking communities, choosing the instruction language for technology can decide the community’s competitive edge in the global market, which conflicts with a critical issue of technocultural sovereignty. On top of that, selecting a language for technology can further create additional barriers and divisions within the community.
Through this co-writing project, I wanted to hear from a non-English speaking community (in this case, artists based in Seoul). We had fruitful conversations on the internationalization of the FES and related technocultural issues during the process, which I want to share with the p5js community.
Co-writers:
Editor:
Rationale
For an open-source project aspiring to reach international learners, it makes sense to try to reach people who are unable to navigate the English-dominant open-source platforms. For non-English speaking communities, choosing the instruction language for technology can decide the community’s competitive edge in the global market, which conflicts with a critical issue of technocultural sovereignty. On top of that, selecting a language for technology can further create additional barriers and divisions within the community.
Through this co-writing project, I wanted to hear from a non-English speaking community (in this case, artists based in Seoul). We had fruitful conversations on the internationalization of the FES and related technocultural issues during the process, which I want to share with the p5js community.
Goals
- To generate the first version of the p5.js FES translation in Korean.
- To develop the first version of internationalization and writing guidelines for friendly errors.
- To collect feedback on the p5.js FES (and its documentation) from Korean communities.
- To archive current issues on technology and language in Korean communities.
- To set a precedent on translating the p5js FES collaborating with a local community.
Participants
Co-writers:
- 염인화 (Inhwa Yeom): artist/XR researcher based in South Korea. (Take a look at her works on p5 for 50+ (Processing Foundation Fellows 2020) and p5js website Korean translation)
- 전유진 (Youjin Jeon): artist/organizer based in Seoul, South Korea. 여성을 위한 열린 기술랩(Woman Open Tech Lab.kr) and Seoul Express
- 정앎 (Alm Chung, organizer): Korean-American artist/researcher based in Seattle, WA.
Editor:
- 이지현 (Jihyun Lee): Korean publishing editor based in South Korea
Examples of different translations by writers and machine translation tools are shown above. For the FES welcome message, six different translations were generated, and a discussion on what is ‘friendly’ in the context of Korean culture ensued.
Our team first translated the existing English error messages of FES. In addition to our drafts, we added machine translations from popular translation tools used in Korea: Google Translate and Naver Papago for reference.
We then generated comments on some selected translations, followed by an asynchronous critique session on the translations. We collected all notes and scripts generated from the critique session to identify 5–6 core issue topics for creating the internationalization and writing guideline.
Below is the list of these topics:
Below is the list of these topics:
- How to create a voice for FES?
— Who is our audience? How should we think of skill and ability if we design for accessibility?
— What is ‘friendly’ for Korean people? Scale and scope of friendliness within the context of Korean culture
— How to create a conversational agent persona based on the community Code of Conduct? (FES as a member of the p5.js community) - What are the challenges for translating from English to Korean?
— Challenges of translating domain-specific, technical terms
— Resources for Korean translation (writing effectively and clearly in Korean) - Who/what are we connecting through translation?
— Machine translation for technical translation and other platforms for translation
p5.js: Friendly Error System
Open source contribution to p5.js (javascript library for creative coding).
2017. 2021-
p5.js Friendly Error System (FES) provides supplementary error messages to make debugging process more accessible.
Starting from examining language-specific common error cases, I developed FES which creates console messages that can hint at the debugging solution rather than throw an error and exit.
FES live example
FES live example (with Korean intro)
JavaScript often allows “silent failures”, meaning the code will fail to execute the expected behavior without a warning (i.e. error messages) from the debugger. For example, JavaScript doesn’t support type checking by default, making errors in parameter entry harder to detect for new JavaScript developers.
From the 2017 FES project write-up:
Consider how much time we spend on debugging. It’s easy to imagine how an effective debugger can cut down development time. What we often overlook is the mood we are in during the programming experience. After all, at the core, the experience of programming resembles an endless back-and-forth communication between the programmer and the debugger.
The voice of a debugger will have an impact on new developers’ first impression and following coding experience. This is why designing a friendly debugger and error system is essential for projects with an outreach mission such as Processing and p5.js. Having a well-designed debugger written in the right tone can lower the barrier for inexperienced users.
p5.js’s new feature, the Friendly Error System (FES), was developed with this idea in mind. Started from examining language-specific common error cases, we developed FES which creates console messages that can hint at the debugging solution rather than throw an error and exit. JavaScript often allows “silent failures”, meaning the code will fail to execute the expected behavior without a warning (i.e. error messages) from the debugger. For example, JavaScript doesn’t support type checking by default, making errors in parameter entry harder to detect for new JavaScript developers.
So far, FES is able to detect and print messages for two kinds of errors: (1) validateParameters() checks a function’s input parameters to confirm it matches the inline documentation and (2) friendlyFileLoadError() catches file loading errors. We have integrated these two kinds of error checking to a selected set of p5 functions, but developers can add them to more p5 functions, or their own libraries, by calling the above FES functions. FES provides a generalized error message generation system, so more error types can be implemented in the future.
To help beginners without requiring additional setup, FES is enabled by default in p5.js. In p5.min.js, it is completely disabled for efficiency. We understand that having an assistant system like FES can be counter-productive and it is possible to easily disable FES by setting `p5.disableFriendlyErrors = true;. I’ll be using p5.js with the default setting in all the following examples.
Without further delay, let’s see FES in action in the ︎︎︎ p5.js Web Editor (FES live example).
Consider how much time we spend on debugging. It’s easy to imagine how an effective debugger can cut down development time. What we often overlook is the mood we are in during the programming experience. After all, at the core, the experience of programming resembles an endless back-and-forth communication between the programmer and the debugger.
The voice of a debugger will have an impact on new developers’ first impression and following coding experience. This is why designing a friendly debugger and error system is essential for projects with an outreach mission such as Processing and p5.js. Having a well-designed debugger written in the right tone can lower the barrier for inexperienced users.
p5.js’s new feature, the Friendly Error System (FES), was developed with this idea in mind. Started from examining language-specific common error cases, we developed FES which creates console messages that can hint at the debugging solution rather than throw an error and exit. JavaScript often allows “silent failures”, meaning the code will fail to execute the expected behavior without a warning (i.e. error messages) from the debugger. For example, JavaScript doesn’t support type checking by default, making errors in parameter entry harder to detect for new JavaScript developers.
So far, FES is able to detect and print messages for two kinds of errors: (1) validateParameters() checks a function’s input parameters to confirm it matches the inline documentation and (2) friendlyFileLoadError() catches file loading errors. We have integrated these two kinds of error checking to a selected set of p5 functions, but developers can add them to more p5 functions, or their own libraries, by calling the above FES functions. FES provides a generalized error message generation system, so more error types can be implemented in the future.
To help beginners without requiring additional setup, FES is enabled by default in p5.js. In p5.min.js, it is completely disabled for efficiency. We understand that having an assistant system like FES can be counter-productive and it is possible to easily disable FES by setting `p5.disableFriendlyErrors = true;. I’ll be using p5.js with the default setting in all the following examples.
Without further delay, let’s see FES in action in the ︎︎︎ p5.js Web Editor (FES live example).
![]()
p5.js: FES Survey Comic
p5.js: FES Survey ComicCommunity survey for p5.js Friendly Error System (FES).
2021-2022.
