diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index 71145223..8a3902ff 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -80,6 +80,10 @@ export default async function createConfigAsync() { label: 'Blog', position: 'right', }, + { + type: 'localeDropdown', + position: 'right', + }, { href: 'https://github.com/oclif/oclif', className: 'header-github-link', @@ -110,5 +114,20 @@ export default async function createConfigAsync() { contextualSearch: true, }, } satisfies Preset.ThemeConfig, + i18n: { + defaultLocale: 'en', + locales: ['en', 'zh'], + localeConfigs: { + en: { + label: 'English', + htmlLang: 'en-US', + }, + zh: { + label: '简体中文', + htmlLang: 'zh-Hans', + path: 'zh' + } + } + } } satisfies Config } diff --git a/website/i18n/zh/code.json b/website/i18n/zh/code.json new file mode 100644 index 00000000..104658b1 --- /dev/null +++ b/website/i18n/zh/code.json @@ -0,0 +1,480 @@ +{ + "theme.ErrorPageContent.title": { + "message": "页面已崩溃。", + "description": "The title of the fallback page when the page crashed" + }, + "theme.BackToTopButton.buttonAriaLabel": { + "message": "回到顶部", + "description": "The ARIA label for the back to top button" + }, + "theme.blog.archive.title": { + "message": "历史博文", + "description": "The page & hero title of the blog archive page" + }, + "theme.blog.archive.description": { + "message": "历史博文", + "description": "The page & hero description of the blog archive page" + }, + "theme.blog.paginator.navAriaLabel": { + "message": "博文列表分页导航", + "description": "The ARIA label for the blog pagination" + }, + "theme.blog.paginator.newerEntries": { + "message": "较新的博文", + "description": "The label used to navigate to the newer blog posts page (previous page)" + }, + "theme.blog.paginator.olderEntries": { + "message": "较旧的博文", + "description": "The label used to navigate to the older blog posts page (next page)" + }, + "theme.blog.post.paginator.navAriaLabel": { + "message": "博文分页导航", + "description": "The ARIA label for the blog posts pagination" + }, + "theme.blog.post.paginator.newerPost": { + "message": "较新一篇", + "description": "The blog post button label to navigate to the newer/previous post" + }, + "theme.blog.post.paginator.olderPost": { + "message": "较旧一篇", + "description": "The blog post button label to navigate to the older/next post" + }, + "theme.blog.post.plurals": { + "message": "{count} 篇博文", + "description": "Pluralized label for \"{count} posts\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.blog.tagTitle": { + "message": "{nPosts} 含有标签「{tagName}」", + "description": "The title of the page for a blog tag" + }, + "theme.tags.tagsPageLink": { + "message": "查看所有标签", + "description": "The label of the link targeting the tag list page" + }, + "theme.colorToggle.ariaLabel": { + "message": "切换浅色/暗黑模式（当前为{mode}）", + "description": "The ARIA label for the navbar color mode toggle" + }, + "theme.colorToggle.ariaLabel.mode.dark": { + "message": "暗黑模式", + "description": "The name for the dark color mode" + }, + "theme.colorToggle.ariaLabel.mode.light": { + "message": "浅色模式", + "description": "The name for the light color mode" + }, + "theme.docs.breadcrumbs.navAriaLabel": { + "message": "页面路径", + "description": "The ARIA label for the breadcrumbs" + }, + "theme.docs.DocCard.categoryDescription.plurals": { + "message": "{count} 个项目", + "description": "The default description for a category card in the generated index about how many items this category includes" + }, + "theme.docs.paginator.navAriaLabel": { + "message": "文件选项卡", + "description": "The ARIA label for the docs pagination" + }, + "theme.docs.paginator.previous": { + "message": "上一页", + "description": "The label used to navigate to the previous doc" + }, + "theme.docs.paginator.next": { + "message": "下一页", + "description": "The label used to navigate to the next doc" + }, + "theme.docs.tagDocListPageTitle.nDocsTagged": { + "message": "{count} 篇文档带有标签", + "description": "Pluralized label for \"{count} docs tagged\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.docs.tagDocListPageTitle": { + "message": "{nDocsTagged}「{tagName}」", + "description": "The title of the page for a docs tag" + }, + "theme.docs.versionBadge.label": { + "message": "版本：{versionLabel}" + }, + "theme.docs.versions.unreleasedVersionLabel": { + "message": "此为 {siteTitle} {versionLabel} 版尚未发行的文档。", + "description": "The label used to tell the user that he's browsing an unreleased doc version" + }, + "theme.docs.versions.unmaintainedVersionLabel": { + "message": "此为 {siteTitle} {versionLabel} 版的文档，现已不再积极维护。", + "description": "The label used to tell the user that he's browsing an unmaintained doc version" + }, + "theme.docs.versions.latestVersionSuggestionLabel": { + "message": "最新的文档请参阅 {latestVersionLink} ({versionLabel})。", + "description": "The label used to tell the user to check the latest version" + }, + "theme.docs.versions.latestVersionLinkLabel": { + "message": "最新版本", + "description": "The label used for the latest version suggestion link label" + }, + "theme.common.editThisPage": { + "message": "编辑此页", + "description": "The link label to edit the current page" + }, + "theme.common.headingLinkTitle": { + "message": "{heading}的直接链接", + "description": "Title for link to heading" + }, + "theme.lastUpdated.atDate": { + "message": "于 {date} ", + "description": "The words used to describe on which date a page has been last updated" + }, + "theme.lastUpdated.byUser": { + "message": "由 {user} ", + "description": "The words used to describe by who the page has been last updated" + }, + "theme.lastUpdated.lastUpdatedAtBy": { + "message": "最后{byUser}{atDate}更新", + "description": "The sentence used to display when a page has been last updated, and by who" + }, + "theme.navbar.mobileVersionsDropdown.label": { + "message": "选择版本", + "description": "The label for the navbar versions dropdown on mobile view" + }, + "theme.NotFound.title": { + "message": "找不到页面", + "description": "The title of the 404 page" + }, + "theme.tags.tagsListLabel": { + "message": "标签：", + "description": "The label alongside a tag list" + }, + "theme.admonition.caution": { + "message": "警告", + "description": "The default label used for the Caution admonition (:::caution)" + }, + "theme.admonition.danger": { + "message": "危险", + "description": "The default label used for the Danger admonition (:::danger)" + }, + "theme.admonition.info": { + "message": "信息", + "description": "The default label used for the Info admonition (:::info)" + }, + "theme.admonition.note": { + "message": "备注", + "description": "The default label used for the Note admonition (:::note)" + }, + "theme.admonition.tip": { + "message": "提示", + "description": "The default label used for the Tip admonition (:::tip)" + }, + "theme.admonition.warning": { + "message": "注意", + "description": "The default label used for the Warning admonition (:::warning)" + }, + "theme.AnnouncementBar.closeButtonAriaLabel": { + "message": "关闭", + "description": "The ARIA label for close button of announcement bar" + }, + "theme.blog.sidebar.navAriaLabel": { + "message": "最近博文导航", + "description": "The ARIA label for recent posts in the blog sidebar" + }, + "theme.CodeBlock.copied": { + "message": "复制成功", + "description": "The copied button label on code blocks" + }, + "theme.CodeBlock.copyButtonAriaLabel": { + "message": "复制代码到剪贴板", + "description": "The ARIA label for copy code blocks button" + }, + "theme.CodeBlock.copy": { + "message": "复制", + "description": "The copy button label on code blocks" + }, + "theme.CodeBlock.wordWrapToggle": { + "message": "切换自动换行", + "description": "The title attribute for toggle word wrapping button of code block lines" + }, + "theme.DocSidebarItem.expandCategoryAriaLabel": { + "message": "展开侧边栏分类 '{label}'", + "description": "The ARIA label to expand the sidebar category" + }, + "theme.DocSidebarItem.collapseCategoryAriaLabel": { + "message": "折叠侧边栏分类 '{label}'", + "description": "The ARIA label to collapse the sidebar category" + }, + "theme.NavBar.navAriaLabel": { + "message": "主导航", + "description": "The ARIA label for the main navigation" + }, + "theme.TOCCollapsible.toggleButtonLabel": { + "message": "本页总览", + "description": "The label used by the button on the collapsible TOC component" + }, + "theme.NotFound.p1": { + "message": "我们找不到您要找的页面。", + "description": "The first paragraph of the 404 page" + }, + "theme.NotFound.p2": { + "message": "请联系原始链接来源网站的所有者，并告知他们链接已损坏。", + "description": "The 2nd paragraph of the 404 page" + }, + "theme.navbar.mobileLanguageDropdown.label": { + "message": "选择语言", + "description": "The label for the mobile language switcher dropdown" + }, + "theme.blog.post.readMore": { + "message": "阅读更多", + "description": "The label used in blog post item excerpts to link to full blog posts" + }, + "theme.blog.post.readMoreLabel": { + "message": "阅读 {title} 的全文", + "description": "The ARIA label for the link to full blog posts from excerpts" + }, + "theme.blog.post.readingTime.plurals": { + "message": "阅读需 {readingTime} 分钟", + "description": "Pluralized label for \"{readingTime} min read\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.docs.breadcrumbs.home": { + "message": "主页面", + "description": "The ARIA label for the home page in the breadcrumbs" + }, + "theme.docs.sidebar.navAriaLabel": { + "message": "文档侧边栏", + "description": "The ARIA label for the sidebar navigation" + }, + "theme.docs.sidebar.collapseButtonTitle": { + "message": "收起侧边栏", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.collapseButtonAriaLabel": { + "message": "收起侧边栏", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.closeSidebarButtonAriaLabel": { + "message": "关闭导航栏", + "description": "The ARIA label for close button of mobile sidebar" + }, + "theme.navbar.mobileSidebarSecondaryMenu.backButtonLabel": { + "message": "← 回到主菜单", + "description": "The label of the back button to return to main menu, inside the mobile navbar sidebar secondary menu (notably used to display the docs sidebar)" + }, + "theme.docs.sidebar.toggleSidebarButtonAriaLabel": { + "message": "切换导航栏", + "description": "The ARIA label for hamburger menu button of mobile navigation" + }, + "theme.docs.sidebar.expandButtonTitle": { + "message": "展开侧边栏", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.docs.sidebar.expandButtonAriaLabel": { + "message": "展开侧边栏", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.SearchBar.seeAll": { + "message": "查看全部 {count} 个结果" + }, + "theme.SearchPage.documentsFound.plurals": { + "message": "找到 {count} 份文件", + "description": "Pluralized label for \"{count} documents found\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.SearchPage.existingResultsTitle": { + "message": "「{query}」的搜索结果", + "description": "The search page title for non-empty query" + }, + "theme.SearchPage.emptyResultsTitle": { + "message": "在文档中搜索", + "description": "The search page title for empty query" + }, + "theme.SearchPage.inputPlaceholder": { + "message": "在此输入搜索字词", + "description": "The placeholder for search page input" + }, + "theme.SearchPage.inputLabel": { + "message": "搜索", + "description": "The ARIA label for search page input" + }, + "theme.SearchPage.algoliaLabel": { + "message": "通过 Algolia 搜索", + "description": "The ARIA label for Algolia mention" + }, + "theme.SearchPage.noResultsText": { + "message": "未找到任何结果", + "description": "The paragraph for empty search result" + }, + "theme.SearchPage.fetchingNewResults": { + "message": "正在获取新的搜索结果...", + "description": "The paragraph for fetching new search results" + }, + "theme.SearchBar.label": { + "message": "搜索", + "description": "The ARIA label and placeholder for search button" + }, + "theme.SearchModal.searchBox.resetButtonTitle": { + "message": "清除查询", + "description": "The label and ARIA label for search box reset button" + }, + "theme.SearchModal.searchBox.cancelButtonText": { + "message": "取消", + "description": "The label and ARIA label for search box cancel button" + }, + "theme.SearchModal.startScreen.recentSearchesTitle": { + "message": "最近搜索", + "description": "The title for recent searches" + }, + "theme.SearchModal.startScreen.noRecentSearchesText": { + "message": "没有最近搜索", + "description": "The text when no recent searches" + }, + "theme.SearchModal.startScreen.saveRecentSearchButtonTitle": { + "message": "保存这个搜索", + "description": "The label for save recent search button" + }, + "theme.SearchModal.startScreen.removeRecentSearchButtonTitle": { + "message": "从历史记录中删除这个搜索", + "description": "The label for remove recent search button" + }, + "theme.SearchModal.startScreen.favoriteSearchesTitle": { + "message": "收藏", + "description": "The title for favorite searches" + }, + "theme.SearchModal.startScreen.removeFavoriteSearchButtonTitle": { + "message": "从收藏列表中删除这个搜索", + "description": "The label for remove favorite search button" + }, + "theme.SearchModal.errorScreen.titleText": { + "message": "无法获取结果", + "description": "The title for error screen of search modal" + }, + "theme.SearchModal.errorScreen.helpText": { + "message": "你可能需要检查网络连接。", + "description": "The help text for error screen of search modal" + }, + "theme.SearchModal.footer.selectText": { + "message": "选中", + "description": "The explanatory text of the action for the enter key" + }, + "theme.SearchModal.footer.selectKeyAriaLabel": { + "message": "Enter 键", + "description": "The ARIA label for the Enter key button that makes the selection" + }, + "theme.SearchModal.footer.navigateText": { + "message": "导航", + "description": "The explanatory text of the action for the Arrow up and Arrow down key" + }, + "theme.SearchModal.footer.navigateUpKeyAriaLabel": { + "message": "向上键", + "description": "The ARIA label for the Arrow up key button that makes the navigation" + }, + "theme.SearchModal.footer.navigateDownKeyAriaLabel": { + "message": "向下键", + "description": "The ARIA label for the Arrow down key button that makes the navigation" + }, + "theme.SearchModal.footer.closeText": { + "message": "关闭", + "description": "The explanatory text of the action for Escape key" + }, + "theme.SearchModal.footer.closeKeyAriaLabel": { + "message": "Esc 键", + "description": "The ARIA label for the Escape key button that close the modal" + }, + "theme.SearchModal.footer.searchByText": { + "message": "搜索提供", + "description": "The text explain that the search is making by Algolia" + }, + "theme.SearchModal.noResultsScreen.noResultsText": { + "message": "没有结果：", + "description": "The text explains that there are no results for the following search" + }, + "theme.SearchModal.noResultsScreen.suggestedQueryText": { + "message": "试试搜索", + "description": "The text for the suggested query when no results are found for the following search" + }, + "theme.SearchModal.noResultsScreen.reportMissingResultsText": { + "message": "认为这个查询应该有结果？", + "description": "The text for the question where the user thinks there are missing results" + }, + "theme.SearchModal.noResultsScreen.reportMissingResultsLinkText": { + "message": "请告知我们。", + "description": "The text for the link to report missing results" + }, + "theme.SearchModal.placeholder": { + "message": "搜索文档", + "description": "The placeholder of the input of the DocSearch pop-up modal" + }, + "theme.ErrorPageContent.tryAgain": { + "message": "重试", + "description": "The label of the button to try again rendering when the React error boundary captures an error" + }, + "theme.common.skipToMainContent": { + "message": "跳到主要内容", + "description": "The skip to content label used for accessibility, allowing to rapidly navigate to main content with keyboard tab/enter navigation" + }, + "theme.tags.tagsPageTitle": { + "message": "标签", + "description": "The title of the tag list page" + }, + "theme.unlistedContent.title": { + "message": "未列出页", + "description": "The unlisted content banner title" + }, + "theme.unlistedContent.message": { + "message": "此页面未列出。搜索引擎不会对其索引，只有拥有直接链接的用户才能访问。", + "description": "The unlisted content banner message" + }, + "hero.title": { + "message": "开源 CLI 框架", + "description": "The homepage hero title" + }, + "hero.subtitle": { + "message": "创建用户喜欢的命令行工具", + "description": "The homepage hero subtitle" + }, + "row.desc": { + "message": "oclif 是一个开源框架，用于在 Node.js 和 TypeScript 中构建命令行接口(CLI)。创建带有多个标志的 CLI 或具有子命令的高级 CLI。oclif 使您很容易为您的公司、服务或您自己的开发需求构建 CLI。", + "description": "The homepage description" + }, + "row.button": { + "message": "开始使用 →", + "description": "The homepage button" + }, + "feature_1.title": { + "message": "整装待发", + "description": "The title of the first feature" + }, + "feature_1.desc": { + "message": "搭建一个功能齐全的 CLI，以便快速入门。Oclif 将我们多年的经验打包成开箱即用的功能，用于参数解析、命令测试和 CLI 特性的自动文档化。", + "description": "The description of the first feature" + }, + "feature_2.title": { + "message": "开源", + "description": "The title of the second feature" + }, + "feature_2.desc": { + "message": "Oclif 是{linkString}的，可以自由使用或修改。我们认为你也会喜欢它，你也可以帮助它变得更好。", + "description": "The description of the second feature" + }, + "feature_2.desc.link": { + "message": "开源", + "description": "open source" + }, + "feature_3.title": { + "message": "可扩展", + "description": "The title of the Third feature" + }, + "feature_3.desc": { + "message": "你或你的用户可以使用插件轻松地扩展 CLI 功能以满足自定义需求。插件是模块化的、可共享的，鼓励重用。", + "description": "The description of the Third feature" + }, + "feature_4.title": { + "message": "值得信赖", + "description": "The title of the Fourth feature" + }, + "feature_4.desc": { + "message": "Oclif 被活跃地用于构建 {Heroku} 和 {Salesforce}，每天为开发人员提供数以百万计的交互。", + "description": "The description of the Fourth feature" + }, + "footer.title": { + "message": "使用 {logoImg} 构建 CLI", + "description": "The title of the footer" + }, + "footer.desc": { + "message": "使用 oclif，您可以为企业、开源项目或自己的开发工作流程构建命令行工具。看看别人都做了些什么。", + "description": "The description of the footer" + } +} diff --git a/website/i18n/zh/docusaurus-plugin-content-blog/2018-03-20-introducing-oclif.md b/website/i18n/zh/docusaurus-plugin-content-blog/2018-03-20-introducing-oclif.md new file mode 100644 index 00000000..7010518c --- /dev/null +++ b/website/i18n/zh/docusaurus-plugin-content-blog/2018-03-20-introducing-oclif.md @@ -0,0 +1,10 @@ +--- +author: Jeff Dickey +title: 介绍 oclif +--- + +![Introducing oclif](/img/2018-03-20-introducing-oclif/header.png) + +Coding for the browser takes serious time. You need to deal with front-end JS, CSS, design, product, and a ton more. On the other hand, building for a CLI takes a fraction of the effort. This makes CLIs particularly great for prototyping out new functionality, offering admin/internal tools, or power-user functionality. + +Read More diff --git a/website/i18n/zh/docusaurus-plugin-content-blog/2019-02-20-cli-flags-explained.md b/website/i18n/zh/docusaurus-plugin-content-blog/2019-02-20-cli-flags-explained.md new file mode 100644 index 00000000..fb9efbd2 --- /dev/null +++ b/website/i18n/zh/docusaurus-plugin-content-blog/2019-02-20-cli-flags-explained.md @@ -0,0 +1,162 @@ +--- +author: Casey Watts and Jeff Dickey +title: 解释 CLI 标志 +--- + +`oclif` makes it easy to create a command line interface (CLI) in node. Most commands have **parameters** — also known as "flags", "args", and sometimes "options". This blog post explains what these parameters are and when to use them. We also have a new feature that makes it easier for users to detect typos when using parameters. + +_Note the following describes GNU-style flags. Not all CLIs follow this convention, but it is the most commonly used._ + +## Parts of Speech + +Any command line interface command has a few standard "parts of speech". As a user of CLI tools, knowing these parts of speech can help you make fewer typos. It can also help you understand complex commands other people share with you more quickly. If you are designing a CLI tool it is even more important to understand these parts of speech, so you can come up with the most ergonomic interface for your users. + + +Of the many ways you can pass data to a CLI command, three of them are **parameters** that are always to the "right" of the command. The three types of parameters are **argument**, **short flag**, and **long flag**. + +### Example `ls` +One of the most common and simplest unix commands is `ls` which "lists" the contents of a directory. + +#### command + +``` +ls +``` + +This command `ls` works on its own, as a standalone **command**. Without any parameters this command will list the contents of the current folder, using an implied `.` directory. + +#### argument + +``` +ls . +ls ~/code/some-repo-name +``` + +If you pass a command **argument** to this command, like the directory name `.` (current folder) or `~/code/some-repo-name`, it will list the contents of that directory instead. + +An argument is anything to the right of a command that is not a flag. An argument can come before or after flags. + +#### Long flag +To list additional files that are normally hidden (like `~/.bashrc`), you can use a flag on the `ls` command. `ls --all` is the **long flag** form. A long flag always uses a double dash, and it is always represented by multiple characters. + +``` +ls --all +ls . --all +``` + +#### Short flag + +There is also a **short flag** form of this flag: `ls -a`. The `a` is short for `all` in this case. A short flag always uses a single dash, and it is always represented by a single letter. + +``` +ls -a +ls . -a +``` + +Short flags can **stack** too, so you don't need a separate dash for each one. Order does not matter for these, unless passing a flag argument. + +``` +ls -la +``` + +#### Flag arguments +Many flags accept an **option**, which is a "flag argument" (as opposed to a "command argument"). In general a command's parameters can be in any order, but flags that accept options must have the option directly after the flag. + +For an example, here the `-x` flag does not accept an option but the `-f` flag does. `archive.tar` is the option being passed to `-f`. + +``` +tar -x -f archive.tar +tar -xf archive.tar +``` + +A flag and its option can be separated by a space ` ` or an equals sign `=`. Interestingly, short flags (but not long flags) can even skip the space, although many people find it much easier to read with the space or equals sign. + +These three are all valid and equivalent: + +``` +tar -f archive.tar +tar -f=archive.tar +tar -farchive.tar +``` + +Long flags must have a space or equals sign to separate the flag from its option. + +``` +git log --pretty=oneline +git log --pretty oneline +``` + +## Other Ways of Passing Data + +We've covered **parameters**, which are **arguments**, **short flags** and **long flags**. There are two other ways to pass data to a command: **environment variables** ("env vars"), or **standard input** ("stdin"). These won't be covered in this blog post. + + +## Designing a Command + +Scenario: we want to design an oclif command that echos an input like "Casey", and returns "hi, Casey!". There are many ways the user could pass this in, and here we show an example of each type of input. + +### argument + +``` +greet-me Casey +``` + +### short flag with argument + +``` +greet-me -n Casey +greet-me -n=Casey +greet-me -nCasey +``` + +### long flag with argument + +``` +greet-me --name=Casey +greet-me --name Casey +``` + +### environment variable + +``` +NAME=Casey greet-me +``` + +### standard input + +``` +echo "Casey" | greet-me +``` + +## Command ergonomics + +### Short flag vs long flag +Many CLI commands allow for both long flag and short flag forms. In the Heroku CLI every flag has at least a long flag form and roughly half of the flags also have a short flag form. + +The long flag form is easier to read, but takes more characters to type. It is often most useful when you want someone to understand a particular command statement quickly and easily, such as in a README. + +The short flag form is quicker to type, and is often better for frequently used commands. Short flags are especially useful when stacking short flags together. + + + diff --git a/website/i18n/zh/docusaurus-plugin-content-blog/2019-09-16-oclifconf-recap.md b/website/i18n/zh/docusaurus-plugin-content-blog/2019-09-16-oclifconf-recap.md new file mode 100644 index 00000000..1dd8f6db --- /dev/null +++ b/website/i18n/zh/docusaurus-plugin-content-blog/2019-09-16-oclifconf-recap.md @@ -0,0 +1,43 @@ +--- +title: "oclifconf 2019: 扼要重述" +--- + +In May, Heroku and Salesforce Open Source organized [oclifconf](https://oclif.io/conf), a conference for developers & product managers building CLI tools on top of [the open source oclif framework](https://github.com/oclif/oclif). The speakers came from various tech companies, such as Adobe, Netlify, and Apollo, who have already built amazing CLI experiences. The topics covered everything from the incredible capabilities oclif has unlocked, to the community-built plugins extending its functionality, and even what the behavior of an adaptive CLI tool might look like. + +Below is a listing of all of the talks from the event, along with a short summary. Enjoy! + +## The future of oclif by Jeff Dickey + + + +In its relatively short lifetime, oclif has already inspired many developers and companies to adopt its framework as a means for implementing their own command-line tooling. In this talk, Jeff Dickey, an oclif founding team member, recaps the project's history and inspiration. He also looks towards the future and outlines some features and improvements that the tool could adapt. This isn't so much a definitive roadmap of where oclif is headed, but rather, a call to inspiration for developers eager to contribute! And if you are interested in contributing, check out the [open issues](https://github.com/oclif/oclif/issues) in the oclif GitHub repo and come say "Hello!" on [Spectrum Chat](https://spectrum.chat/oclif). + +## Open Source Citizenship by Josh Simmons + + + +When it comes to open source, it's more than just individuals now. More and more frequently, large corporations are contributing to projects by donating to contributors, sponsoring events, or upstreaming contributions. But keeping open source projects and communities healthy requires more than just money and brainpower. Josh Simmons surveyed multiple open source communities and relays his findings as to what help maintainers and contributors actually need in this talk. + +## Building an enterprise-grade CLI with oclif by Thomas Dvornik + + + +Security and performance are all about trust. While oclif is an extremely extensible framework for building CLI tooling, there are additional requirements to fulfill for enterprise businesses to adopt it that might not be necessary for individual developers. Thomas Dvornik outlines what he and his colleagues at Salesforce have implemented as plugins to oclif to satisfy these needs, including encrypted OAuth, plugin signing, lazy loading dependencies, synchronizing weekly releases and deprecations across dozens of repositories, and establishing cross-team coding and documentation standards. + +## How Adobe I/O built an extensible CLI with oclif by Jesse MacFadyen + + + +Perhaps oclif's most appealing feature is its support for plugins. In Cordova's case, they've created a sophisticated telemetry system that helps Adobe developers see which commands users are using--and reports on which ones are erroring out. By embedding a feedback system into the tool, users are even able to quickly send their suggestions to a form, without ever leaving the terminal. Jesse MacFadyen demonstrates how oclif's plugin system can work beyond simply executing commands. + +## Integrating oclif with GraphQL and Apollo by Evans Hauser + + + +For Evans Hauser and the team at Apollo, oclif is best thought of as "React for the CLI." As a client paired with a strongly-typed API contract to a server, it can deliver structured and consistent commands to retrieve external data. What better mechanism to use for this transfer than GraphQL, a framework which empowers the client to ask precisely for the data it needs, and nothing more? + +## Adaptive Intent-based CLI State Machines by Shawn Wang + + + +In designing oclif, [Jeff Dickey wrote out 12 CLI factors to keep in mind](https://medium.com/@jdxcode/12-factor-cli-apps-dd3c227a0e46). In this talk, Shawn Wang outlines a 13th: state. State is hard, because it depends on context, and context depends on understanding what a user intends to do, not what they are asking. Shawn is working towards enabling oclif to better understand the commands a user has entered, so that it can predict and interpret future commands that might be entered next. This would enable CLI tools to not just interpret a users' commands, but to also interpret their intent. diff --git a/website/i18n/zh/docusaurus-plugin-content-blog/2019-10-31-oclif-node-updates.md b/website/i18n/zh/docusaurus-plugin-content-blog/2019-10-31-oclif-node-updates.md new file mode 100644 index 00000000..5372f4c6 --- /dev/null +++ b/website/i18n/zh/docusaurus-plugin-content-blog/2019-10-31-oclif-node-updates.md @@ -0,0 +1,67 @@ +--- +title: oclif 的 Current Node 版本支持 +--- + +To maintain a healthy project trajectory, oclif follows and supports [Node Active LTS release](https://nodejs.org/en/about/releases/), currently Node 10 & Node 12. This means ensuring that oclif continues to play nice with coming Active LTS Node versions and other packages in the ecosystem. Moving forward also means leaving older versions behind. Starting in 2020, Node will stop maintaining [Node 8](https://github.com/nodejs/Release#release-schedule) and it is our intent at that time to also follow suit. Let’s take a look at a few ways we will be supporting these changes. + +## CI Environments + +CLIs created with the oclif cli going forward will be generated with a CircleCI configuration with Node 10 & 12 and an Appveyor configuration using Node 10. We have also added Node latest to CircleCi to be an early warning detection against coming Node changes (Node latest is managed by CircleCI). + +We have already updated every oclif repo's CI configs to reflect this. + +If your existing CLI uses either Appveyor or CircleCI you can update your config files also, like so: + +### .circleci/config.yml + +Your CircleCI config should contain a `node-latest` job, aliased as `test`. From this, there should be two extensions of this job for the Active LTS Node versions, Node 10 and Node 12. + +``` + node-10: + <<: *node-latest + docker: + - image: node:10 + node-12: + <<: *node-latest + docker: + - image: node:12 +``` + +Notice that these declarations only change the Docker Node images used to run that job. + +Additionally, the jobs listed within workflows must also be updated to reflect our changes in configuration: + +``` + jobs: + - node-latest + - node-10 + - node-12 +``` + +### appveyor.yml + +For appveyor we are currently only testing the oldest Active LTS Node version, Node 10. Update the `nodejs_version` proppert in your appveyor.yml file to reflect this. + +``` +environment: + nodejs_version: "10" +``` + + +## Deprecating Node 8 & Updating packge.json engines + +In Jan 2020, Node will end its Node 8 maintenance. We will follow suit by setting the package.json engine property in oclif packages to `>=10` and bumping the package's major versions. + +Depending on how you ship your CLI you may wish to also bump the engines version in your CLI's package.json. You can read more about the implications of the engines property configuration in the [npm documentation](https://docs.npmjs.com/files/package.json#engines). + +Also consider distributing your CLI with [its own Node version](https://oclif.io/docs/releasing#standalone-tarballs). + +## Packaged Node Version + +When using dev-cli to pack your CLI it will use the Node version as specified in your package.json under the `oclif.update.node.version` property. This value should reflect an Active LTS Node version (dev-cli does not currently enforce versions). + +## Supporting the future + +As a community we may discover bumps along the way as we upgrade. If you notice something related to oclif please feel free to open an issue or submit a pull request under the relevant oclif package within [the org](https://github.com/oclif). + +We look forward to using the latest from Node and the community and keeping oclif healthy along the way. diff --git a/website/i18n/zh/docusaurus-plugin-content-blog/2019-12-05-oclif-eslint-migration.md b/website/i18n/zh/docusaurus-plugin-content-blog/2019-12-05-oclif-eslint-migration.md new file mode 100644 index 00000000..f2713882 --- /dev/null +++ b/website/i18n/zh/docusaurus-plugin-content-blog/2019-12-05-oclif-eslint-migration.md @@ -0,0 +1,71 @@ +--- +title: oclif 从 TSLint 到 ESLint 的迁移 +--- + +Back in February of this year, plans were announced to [deprecate TSLint](https://github.com/palantir/tslint/issues/4534) in favor of ESLint. TSLint's goal has become to work toward a “unified developer experience” by supporting ESLint development going forward. + + + +## What has changed in oclif + +To keep inline with the community, oclif has transitioned to ESLint for all our core libraries as well as all our official plugins. + +Starting in v1.15.x, oclif will now optionally generate projects with ESLint for both TypeScript and JavaScript CLI’s. + +ESLint does require Node to be on stable LTS version, at the time of writing, Node 8.10.x, Node 10.13.x & Node 12.x.x. + +## How does this affect you + +Existing CLI’s are unchanged, but any newly generated CLI's will only give the option of using ESLint. If you are running tslint in your CLI, we recommend you switch to ESLint as well. + +In migrating our projects we took the following steps (for an example of these changes see this [pull request](https://github.com/oclif/githubcli/pull/10)). + +1. Install eslint + + `$ yarn add eslint eslint-config-oclif eslint-config-oclif-typescript --dev` +2. Add eslint related files +```shell +$ echo '{ + "extends": [ + "oclif", + "oclif-typescript" + ], + "rules": { + } +}' > .eslintrc +``` +3. Remove tslint and related packages + + `$ yarn remove @oclif/tslint tslint` +4. Remove tslint related configuration files + + `$ rm tslint.json` +5. Change lint script in our package.json from something like: + + `"lint": "tsc -p test --noEmit && tslint -p test -t stylish"` + + to + + `"lint": "eslint . --ext .ts --config .eslintrc"` + +To preserve the test compile (tsc -p test --noEmit) we also made the following updates to our scripts: + +`"pretest": "tsc -p test --noEmit"` + +In some cases we had our posttest duplicating the same steps as our lint script so it’s cleaner to have it reference the lint job directly with: + +`"posttest": "yarn lint"` + + +6. Run `yarn lint --fix`. This attempts to auto-fix any linting violations automatically. In the case an auto-fix isn’t available it should be fixed manually or ignored (see the [eslint configuration doc](https://eslint.org/docs/user-guide/configuring) for more information) +7. Do a search in the codebase for `tslint` and remove any unnecessary tslint disabling comments, like: +```javascript +/* tslint:disable:object-literal-sort-keys */ +``` + + +If you are on a version of Node that is not supported by ESLint, you will also need to update your Node engine. ESLint supports Node 8, 10, and 12 so you should upgrade to the most recent Node version compatible with your CLI and also supported by ESLint (see ESLint's [Installation and Usage](https://www.npmjs.com/package/eslint#installation-and-usage) instructions). + +## When will this take effect + +These changes have taken effect in oclif v1.15.1. When you generate a new CLI or plugin it will now contain configuration for ESLint instead of TSLint. diff --git a/website/i18n/zh/docusaurus-plugin-content-blog/2020-05-05-introducing-custom-help-classes.md b/website/i18n/zh/docusaurus-plugin-content-blog/2020-05-05-introducing-custom-help-classes.md new file mode 100644 index 00000000..e8a2854a --- /dev/null +++ b/website/i18n/zh/docusaurus-plugin-content-blog/2020-05-05-introducing-custom-help-classes.md @@ -0,0 +1,60 @@ +--- +title: 在 oclif 中自定义帮助 +--- + +Out of the box oclif provides a great help experience for CLIs. + +But what if, as an oclif developer, you want to customize some or all of the output? + +You can now customize your CLI's help output by implementing the `HelpBase` abstract class. + +## Getting started with custom help + +If you have not done so yet, update `@oclif/core`. + + +``` +$ yarn add --latest @oclif/core +``` + +To get started, first define the filepath to your help class in oclif's config in package.json. This is a relative path to the help class, without a file extension. + +For this example, the help class will be created in a file at "[project root]/src/help.ts". + +``` +{ + // ... + "oclif": { + "helpClass": "./lib/help" + // ... + } + // ... +} +``` + +From here there are two paths, implement the `HelpBase` abstract class yourself or overwrite the parts of the default `Help` class you want to customize (ex: how command usage is displayed). We recommend the latter approach but cover both in the new [Help Classes docs](/docs/help_classes). + + +## Separating TOPICS & COMMANDS in the new default `Help` class + +Previously, topics and child commands were listed in help output under a single list heading called "COMMANDS". But we found this can be slightly confusing. Some topics are commands also (a.k.a. topic-commands) while others are simply organizational namespacing (and when ran just show their help). + +The new default `Help` class splits the list of children into distinct lists of "TOPICS" and "COMMANDS", with the possibility of an item appearing in both if it a topic-command. This makes it clearer what is expected to be ran - "COMMANDS" - and what is providing structure - "TOPICS" - when looking at the help output. + +``` +VERSION + plugin-help-example/0.0.0 darwin-x64 node-v12.12.0 + +USAGE + $ plugin-help-example [COMMAND] + +TOPICS + topic this is a topic and has child topics or commands + +COMMANDS + hello describe the command here + help display help for plugin-help-example +``` + +We look forward to seeing what custom help features you implement in your oclif CLIs with this new feature! + diff --git a/website/i18n/zh/docusaurus-plugin-content-blog/2020-07-01-pretty-printable-errors.md b/website/i18n/zh/docusaurus-plugin-content-blog/2020-07-01-pretty-printable-errors.md new file mode 100644 index 00000000..edbb1834 --- /dev/null +++ b/website/i18n/zh/docusaurus-plugin-content-blog/2020-07-01-pretty-printable-errors.md @@ -0,0 +1,28 @@ +--- +title: 漂亮的打印错误 +--- + +Often CLIs are used as handy tools and when things go wrong it’s useful to have additional context. In oclif we have added a couple of additional properties that can show extra context to the users when an error is displayed. The `code`, `ref` and `suggestions` will now be displayed if they are included. This will work with an existing oclif CLI by adding the latest @oclif/errors and @oclif/core to the CLI's package.json dependencies. + +For example, using `this.error` with the additional properties: +```js +class TestError extends Command { + async run() { + this.error("An error has occurred!", { + code: "OCLIF_ERR", + ref: "https://oclif.io/docs/commands#thiserrormessage-string--error-options-code-string-exit-number", + suggestions: ["Use these extra properties to provide additional context"], + }) + } +} +``` + +would result with the following output: +```text +› Error: An error has occurred! +› Code: OCLIF_ERR +› Try this: Use these extra properties to provide additional context +› Reference: https://oclif.io/docs/commands#thiserrormessage-string--error-options-code-string-exit-number +``` + +If these properties are not provided then nothing changes and the CLI will continue to display the single error message output as it did before. Additionally, as part of this exercise we’ve added documentation around [Error Handling in oclif](/docs/error_handling) which should come in handy if the need arises to extend oclif’s default handling of errors. diff --git a/website/i18n/zh/docusaurus-plugin-content-blog/2020-08-26-summer-update.md b/website/i18n/zh/docusaurus-plugin-content-blog/2020-08-26-summer-update.md new file mode 100644 index 00000000..90d58757 --- /dev/null +++ b/website/i18n/zh/docusaurus-plugin-content-blog/2020-08-26-summer-update.md @@ -0,0 +1,40 @@ +--- +title: oclif 2020 夏季更新 +--- + +Hello oclif developers! We hope you are all doing well. + +Earlier this year, we started our planning for oclifconf v2 and, like all conference, had to change course. We opted not to hold a virtual conference, however, we wanted to take some time to highlight a few oclif features shipped this year. + +## Feature: Help templating + +One of the most requested features, help templating enables oclif developers to customize the help output for their CLI. + +Read [the announcement](/blog/2020/05/05/introducing-custom-help-classes). + +## Feature: Custom error delegation + +This feature both improved how oclif throws and handles errors and allows oclif developers to overwrite or interject in oclif’s error handling. + +Read [the announcement](/blog/2020/07/01/pretty-printable-errors). + +## Feature: postrun hooks + +We have added a new lifecycle event `postrun`. Your CLI can now run a hook after a command has ran. + +See our [hook documentation](/docs/hooks). + +## Feature: Root index command + +Previously, oclif would display CLI help if only the binary name with no command ID was invoked, oclif now supports a "root index" command. If present, a command defined at `src/commands/index.ts` will be run if no command ID is found. + +## 1 million weekly downloads + +While exact oclif usage metrics are hard to pin down, we use npm download statistics of oclif packages as a rough approximation. Earlier this year, oclif's command package hit 1 million weekly downloads for the first time! + + +This year has been presented its challenges on everyone. We want to thank you, oclif developers, whom have taken the time to use and improve the oclif project. We look forward to seeing you all - in person - in the future! + +All our best, + +The oclif team diff --git a/website/i18n/zh/docusaurus-plugin-content-blog/2021-03-01-introducing-oclif-core.md b/website/i18n/zh/docusaurus-plugin-content-blog/2021-03-01-introducing-oclif-core.md new file mode 100644 index 00000000..7ddc6bf6 --- /dev/null +++ b/website/i18n/zh/docusaurus-plugin-content-blog/2021-03-01-introducing-oclif-core.md @@ -0,0 +1,55 @@ +--- +title: "介绍 @oclif/core" +--- +Greetings! + +We hope this blog post finds you well. + +### Introducing... + +We are excited to announce the next iteration of the oclif project today: `@oclif/core`. + +We have learned a lot in the last three years of developing oclif, developing on oclif and supporting millions of command runs a day via Heroku and Salesforce CLIs. +`@oclif/core` ("Core") simplifies the oclif development experience and introduces highly requested new features. + +Core combines the essential oclif packages into one "core" package, aptly named `@oclif/core`. + +Core also introduces: +- A default command option +- Colon or space command syntax +- Async command parsing +- Command piping to arguments + +With the introduction of default command functionality, Core simplifies the oclif project and removes the notion of single or multi command CLIs. Core CLIs can have 1 or many commands. + +Along with Core, we moved the oclif-dev CLI into the oclif CLI creating a single "utility" CLI. This CLI also introduces a new AWS S3 compatible publishing scheme. + +### What to expect in the near future + +Core is in pre-release beta and being actively developed for new internal Salesforce CLIs. + +Much documentation needs to be written in the coming months including migration paths. Migration onto Core should be as painless as possible with many exports remaining entirely unchanged. Look for forthcoming blog posts and documentation on [oclif.io](https://oclif.io). + +Early this summer, tentively June 1, we will release Core v1. Core's release will coincide with major bumps to many other oclif plugin packages. See the compatibility matrix below. + +At Core's v1 release, the current "main" oclif packages (namely: command, config, errors & parser) will go into maintenance mode until Jan 2022. They will receive _only_ bug and security fixes and they remain compatible with current versions of the oclif and oclif-dev CLIs. Afterwhich, they will be archived. + +Companioning Core, the next major release of the oclif CLI (literally `oclif@2`) will generate Core CLIs. + +### Going forward + +We are excited to release Core! We invite you to poke around the [Core repo](https://github.com/oclif/core). It may appear to be a big change but Core keeps what you already enjoy about oclif while reducing development complexity, project dependencies, package coupling and bundle size and introduces many requested features previously too prickly to weave into the current oclif architecture. + +Best, + +The oclif team + +#### Reference: Compatibility matrix + +| | oclif "v1" | oclif "Core" | +| - | - | -| +| Utility CLIs | oclif@\<2
@oclif/dev-cli@\<2 | oclif@>=2 +| Main packages | @oclif/core@\<2
@oclif/config@\<2
@oclif/errors@\<2
@oclif/parser@\<4
@oclif/plugin-help@\<4
| @oclif/core@>=1 +| Node LTS | Node v8-14 | Node v12+ | +| TypeScript | typescript@\<4 | typescript@>=4 | +| Main plugins | @oclif/plugin-autocomplete@\<1
@oclif/plugin-commands@\<2
@oclif/plugin-help@\<4
@oclif/plugin-not-found@\<2
@oclif/plugin-plugins@\<2
@oclif/plugin-update@\<2
plugin-warn-if-update-available@\<2
plugin-which@\<2
| @oclif/plugin-autocomplete@>=2
@oclif/plugin-commands@>=2
@oclif/plugin-help@>=4
@oclif/plugin-not-found@>=2
@oclif/plugin-plugins@>=2
@oclif/plugin-update@>=2
@oclif/plugin-warn-if-update-available@>=2
@oclif/plugin-which@>=2
| diff --git a/website/i18n/zh/docusaurus-plugin-content-blog/2022-01-12-announcing-oclif-v2.md b/website/i18n/zh/docusaurus-plugin-content-blog/2022-01-12-announcing-oclif-v2.md new file mode 100644 index 00000000..0f5ca994 --- /dev/null +++ b/website/i18n/zh/docusaurus-plugin-content-blog/2022-01-12-announcing-oclif-v2.md @@ -0,0 +1,109 @@ +--- +title: 发布 oclif v2! +--- + +Hello and happy new year! It's our great pleasure to announce that we have released oclif v2, which uses the new [@oclif/core](https://github.com/oclif/core) library! 🎉 + +oclif v2 includes many changes that improve the experience of both creating and using an oclif CLI. + +Going forward, we don't plan to make any updates to oclif v1 and its corresponding libraries, except for critical security fixes. See the [compatibility matrix](#compatibility-matrix) for a list of these libraries. In order to give developers time to migrate from v1 to v2, we're not completely dropping support yet. But at some point in the future we'll archive the v1 repositories and deprecate their versions on npm. + +## What’s changing? + +### Repository Changes + +All repositories under the [oclif org](https://github.com/oclif/) now use `main` as their primary branch and `oclif-v1` as the legacy branch. The `main` branch corresponds to oclif v2 and the `oclif-v1` branch to oclif v1. If you find any repos that don’t have a `main` branch, you can safely assume that they're not used in oclif v2 and will be deprecated in the future. + +### Consolidating Tools & Libraries + +The [`oclif-dev`](https://github.com/oclif/dev-cli) CLI has now been incorporated into [`oclif`](https://github.com/oclif/oclif). You now no longer need to install a separate package to manage your entire CLI’s lifecycle. + +The following libraries have been consolidated under [`@oclif/core`](https://github.com/oclif/core) and will be deprecated at some point in the future. Read the [migration guide](https://github.com/oclif/core/blob/main/MIGRATION.md) to learn how to update your CLI or plugin to use the new core library. + +* `@oclif/command` +* `@oclif/config` +* `@oclif/error` +* `@oclif/help` +* `@oclif/parser` + +### No more single vs multi command CLIs + +There's only one "type" of oclif v2 CLI, but it can have as few or as many commands as a developer wants. As a result, there’s only one command to generate CLIs, `oclif generate`, as opposed to the old `oclif single` and `oclif multi` commands. + +### Node > 12 + +To ensure oclif CLIs are as secure as possible, all v2 libraries and plugins support only Node 12 or higher as of now. Going forward, they'll support only Node Maintenance or higher, as defined by Node's release schedule here: https://nodejs.org/en/about/releases/. + +## What’s new? + +### New example CLI + +[`oclif-hello-world`](https://github.com/oclif/hello-world/) is our new example repo. This is also the repo that's [used as a template](https://github.com/oclif/oclif/blob/edc6616e51/src/generators/cli.ts#L74) when running `oclif generate` to create a new CLI. This repo will always be able to be referenced as an example of what an oclif v2 CLI should look like. + +### Spaced commands + +oclif CLIs can now use spaces, instead of colons, to separate topics and subcommands. To enable this feature, simply add `“topicSeparator": " "` to the oclif config in your package.json. See an example in our [example repo](https://github.com/oclif/hello-world/blob/main/package.json#L55). + +``` +// Old commands that use : +$ mycli do:something +``` +``` +// New spaced commands +$ mycli do something +``` + +> Note: Spaced commands are backwards compatible. So if you enable spaced commands for your CLI, users will still be able to use `:` as a separator. This ensures that any existing scripts don't break. + +### New Help Output + +We’ve revamped the way command help is outputted to the terminal, making it both easier to implement and easier to read. See the difference between the old help output on the left and the new help output on the right in the screenshots below. + + + + + + + + + + +
oclif v1oclif v2
+ +Notice that there are new sections for flags and global flags, examples are displayed with better spacing, and there is a section at the bottom called Configuration Variables. This Configuration Variables section is not part of the new help by default. But we've added support for custom help sections, which is what the `sf` CLI uses to create the new section. + +### Async Command Parsing + +We’ve also improved the performance of new CLIs by rewriting how commands are parsed on initialization. The [new parser](https://github.com/oclif/core/blob/main/src/parser/parse.ts) is asynchronous, which makes CLIs with a lot of commands or installed plugins much faster. + +## What’s coming next? + +Part of our charter for the release of oclif v2 includes improving our engagement with the oclif community. We know that over the past couple of years we’ve reduced our involvement, and a lot of issues and PRs have languished in limbo. Hopefully you’ve already seen increased activity and responses from oclif maintainers recently, but if you haven’t, please don’t hesitate to ping us by tagging [@admins](https://github.com/orgs/oclif/teams/admins) in oclif repos. + +We also want to start interviewing members of the oclif community to acquire feedback and prioritize the features and fixes you deem most important! + +Best, + +The oclif team + +
+ +### Reference material + +#### Migration Guide + +This guide explains how to upgrade a CLI or plugin from the old oclif v1 libraries to the new `@oclif/core` library that oclif v2 uses. + +https://github.com/oclif/core/blob/main/MIGRATION.md + +#### Compatibility Matrix + +The following matrix shows how the v1 libraries and plugins relate to the new v2 ones. Use this matrix as a guide to know what to drop and which versions to switch when upgrading your plugins and CLIs to v2. + +| | oclif "v1" | oclif "v2" | +| - | - | -| +| Utility CLIs | oclif@\<2
@oclif/dev-cli@\<2 | oclif@>=2 +| Main packages | @oclif/command
@oclif/config
@oclif/errors
@oclif/parser
@oclif/plugin-help
| @oclif/core@>=1 +| Node LTS | Node v8-14 | Node v12+ (at time of writing) | +| TypeScript | typescript@\<4 | typescript@>=4 | +| Main plugins | @oclif/plugin-autocomplete@\<1
@oclif/plugin-commands@\<2
@oclif/plugin-help@\<4
@oclif/plugin-not-found@\<2
@oclif/plugin-plugins@\<2
@oclif/plugin-update@\<2
plugin-warn-if-update-available@\<2
plugin-which@\<2
| @oclif/plugin-autocomplete@>=1
@oclif/plugin-commands@>=2
@oclif/plugin-help@>=4
@oclif/plugin-not-found@>=2
@oclif/plugin-plugins@>=2
@oclif/plugin-update@>=2
@oclif/plugin-warn-if-update-available@>=2
@oclif/plugin-which@>=2
| diff --git a/website/i18n/zh/docusaurus-plugin-content-blog/2024-03-29-spring-update.md b/website/i18n/zh/docusaurus-plugin-content-blog/2024-03-29-spring-update.md new file mode 100644 index 00000000..71a49815 --- /dev/null +++ b/website/i18n/zh/docusaurus-plugin-content-blog/2024-03-29-spring-update.md @@ -0,0 +1,57 @@ +--- +title: oclif 2024 春季更新 +--- + +Hello oclif developers! It's been a while since we last uploaded a blog - and *a lot* has happened. + +We've been focusing on these high-level areas over the past couple of years: +- Improving `@oclif/core` +- ESM Support +- Improving and revitalizing oclif.io +- Re-engaging the oclif community + +## Improving `@oclif/core` + +Since we [announced `@oclif/core` over three years ago](/blog/2021/03/01/introducing-oclif-core), we've released two new major versions, each packed with lots of features that we're really excited about. + +Here are some of these changes: +- Full support for ESM and interoperability with CommonJS (more on this topic below). +- Configurable command discovery strategies that give you more control over how commands are loaded at runtime. Check out the [docs](/docs/command_discovery_strategies). +- A new `preparse` hook that allows you to manipulate the provided arguments before they're parsed. Salesforce used this hook to [implement](https://github.com/salesforcecli/cli/pull/1536) a neat `--flags-dir` feature that translates local files into flags. +- A new `Performance` class that you can use to track performance inside of `@oclif/core` and your own CLI or plugin. Check out the [docs](/docs/performance). +- A new flag type, `Flags.option`, that lets you define a flag with a preset list of options. Typescript then uses the options to infer the flag's type. +- Flags now have a `relationship` property that allows you to define more complex relationships between flags. Check out the [flags docs](/docs/flags) for more information. +- Flags now have a `defaultHelp` property that allows you to set the human readable default value in the command help. This property is useful when your flag's `parse` method returns a complex type, such as an object or a class. Check out the [flags docs](/docs/flags) for more. +- Commands now have a `hiddenAliases` property that allows you to define aliases that you want to hide from the user. The property is super helpful when you're trying to wean users off a deprecated command. +- You can now use [bun](https://bun.sh/) or [tsx](https://www.npmjs.com/package/tsx) as dev runtimes (as opposed to node or ts-node). +- A command's usage, args, and flags are now shown whenever a user forgets to provide a required arg or flag, or when they provided a non-existent flag. + +If you need help migrating to the latest version, head over to [core's README](https://github.com/oclif/core/?tab=readme-ov-file#-migrating) which has links to the migration guides. Feel free to open a new [discussion](https://github.com/oclif/core/discussions) if you need more hands-on help from us or the community. + +## ESM Support + +Version 3 of `@oclif/core` introduced full support for developing ESM plugins and CLIs. It also offered full support for interoperability between CommonJS and ESM plugins. + +Put more simply, you can now migrate your CLI to ESM while keeping individual plugins in CommonJS (or vice versa). The upgrade path is now much simpler for you. You also don't need to worry about any community plugins that have migrated to ESM before you did (such as all the `@oclif` plugins) or are staunchly sticking with CommonJS for the foreseeable future. + +Read more about this topic [here](/docs/esm). + +## Improving and Revitalizing oclif.io + +Another area of focus for us has been improving our documentation site, [oclif.io](htttps://oclif.io). + +While improving the quality and accuracy of the documentation was our priority, we also took the time to upgrade to the latest version of [docusaurus](https://docusaurus.io/). This new version gave our site a much-needed facelift, as well as cool new features such as dark mode and announcements. + +If you have any feedback or are running into issues, we want to hear about it. Just create an issue in the [oclif.io repo](https://github.com/oclif/oclif.github.io/issues). + +## Re-engaging the oclif Community + +Lastly, our biggest priority at the moment is to re-engage the oclif community. We understand how frustrating it has been over the years to see your issues and pull requests go unacknowledged. We apologize for not prioritizing the community, and are earnestly trying to make sure that every issue and pull request gets the attention it deserves going forward. + +We also opened up GitHub discussions for [@oclif/core](https://github.com/oclif/core/discussions) and the [oclif CLI](https://github.com/oclif/oclif/discussions), where you can now post your questions or ideas. We hope you take advantage of them, we love hearing from you! + +One last thing: we intend to publicly post our roadmap so you have more visibility into what we're working on. Stay tuned! + +All our best, + +The oclif team diff --git a/website/i18n/zh/docusaurus-plugin-content-blog/2024-04-10-oclif-init.md b/website/i18n/zh/docusaurus-plugin-content-blog/2024-04-10-oclif-init.md new file mode 100644 index 00000000..5c9170e5 --- /dev/null +++ b/website/i18n/zh/docusaurus-plugin-content-blog/2024-04-10-oclif-init.md @@ -0,0 +1,62 @@ +--- +title: Introducing `oclif init` command +--- + +Thanks to the contribution of [@joshcanhelp](https://github.com/joshcanhelp) we released a new command for the `oclif` CLI called `oclif init` in version [4.8.0](https://github.com/oclif/oclif/releases/tag/4.8.0) + +The `oclif init` command allows you to initialize oclif in an existing project directory by adding the bare minimum requirements: a few pieces of configuration, bin scripts, and a couple of dependencies (`@oclif/core` and `ts-node`). This is slightly different from `oclif generate`, which will create an entirely new oclif project based on our [templates](/docs/templates). + +`oclif init` will add the following: +- bin scripts: `bin/run.js`, `bin/run.cmd`, `bin/dev.js`, and `bin/dev.cmd` +- `oclif` section to package.json with `bin`, `dirname`, `commands`, and `topicSeparator` set (See [Configuring Your CLI](/docs/configuring_your_cli) for more) +- `@oclif/core` to `dependencies` in your package.json (if it's not already there) +- `ts-node` to `devDependencies` in your package.json (if it's not already there) + +Once you've initialized oclif, you can use the [bin scripts](/docs/templates#bin-scripts) to execute your CLI. You can also use the other `oclif` commands like `oclif generate command` and `oclif generate hook` to start adding new functionality. + +![oclif init demo](/img/oclif-init-demo.gif) + +``` +❯ oclif init --help +Initialize a new oclif CLI + +USAGE + $ oclif init [--bin ] [--module-type ESM|CommonJS] [--package-manager npm|yarn|pnpm] [--topic-separator + colons|spaces] [-d ] [-y] + +FLAGS + -d, --output-dir= Directory to initialize the CLI in. + -y, --yes Use defaults for all prompts. Individual flags will override defaults. + --bin= Supply answer for prompt: Command bin name the CLI will export + --module-type=