{"id":19777447,"url":"https://github.com/ilib-js/ilib-loctool-ghfm","last_synced_at":"2025-04-30T19:32:28.532Z","repository":{"id":34292726,"uuid":"172763572","full_name":"iLib-js/ilib-loctool-ghfm","owner":"iLib-js","description":"Ilib loctool plugin to parse and localize github-flavored markdown","archived":false,"fork":false,"pushed_at":"2024-11-08T16:42:11.000Z","size":311,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-11-08T22:40:22.543Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iLib-js.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-02-26T18:08:10.000Z","updated_at":"2021-10-14T20:45:49.000Z","dependencies_parsed_at":"2024-10-29T10:21:27.265Z","dependency_job_id":null,"html_url":"https://github.com/iLib-js/ilib-loctool-ghfm","commit_stats":{"total_commits":140,"total_committers":3,"mean_commits":"46.666666666666664","dds":0.2857142857142857,"last_synced_commit":"4db00063852758e801f1d0b2c7b7a98ead38bde1"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-loctool-ghfm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-loctool-ghfm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-loctool-ghfm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-loctool-ghfm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iLib-js","download_url":"https://codeload.github.com/iLib-js/ilib-loctool-ghfm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224222208,"owners_count":17275980,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T05:24:55.570Z","updated_at":"2025-04-30T19:32:28.505Z","avatar_url":"https://github.com/iLib-js.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003e :warning: **Deprecation Notice** :warning:\n\u003e This repository has been deprecated. Please use the corresponding package from the [iLib-js monorepo](https://github.com/iLib-js/ilib-mono) instead.\n\n# ilib-loctool-ghfm\n\nIlib loctool plugin to parse and localize github-flavored markdown\n\nMarkdown is broken into paragraphs and phrases using the\n[remark](https://www.npmjs.com/package/remark) family of parsers.\n\n## Escapes\n\nWhenever there is syntax in the markdown that translators should\nnot touch, this plugin converts them into xml-like components.\n\n```\nThis is _bold_ and *italic* text.\n```\n\nBecomes the string:\n\n```\nThis is \u003cc0\u003ebold\u003c/c0\u003e and \u003cc1\u003eitalic\u003c/c1\u003e text.\n```\n\nfor the translators.\n\nIn this way, translators only have to deal with xml-like syntax\n(which they are probably already familiar with) instead of the\nvarious methods of marking up text using markdown.\n\nEach component is numbered so that the translators can switch\nthem around as appropriate for the grammar of their target\nlanguage.\n\n## Code\n\nSnippets of code are not processed. If there is an inline\nsnippet of code, it will be considered part of the surrounding\ntext and represented as an XML-like component. The text of\nthe inline snippet will be put into the comments of the\nextracted string so that the translator knows what it is.\n\nExample:\n\n```\nThere are many instances of `numcount` used in the code.\n```\n\nbecomes:\n\n```\nThere are many instances of \u003cc0/\u003e used in the code.\n```\n\nfor the translators.\n\nInline snippets are represented with self-closing XML tags.\n\n## HTML\n\nYou may embed HTML in the markdown and it will be processed as\nabove using the XML-like components.\n\n```\nThis text is \u003cb\u003ebold\u003c/b\u003e and contains a \u003cspan font=\"foo\"\u003edifferent font\u003c/span\u003e.\n```\n\nbecomes:\n\n```\nThis text is \u003cc0\u003ebold\u003c/c0\u003e and contains a \u003cc1\u003edifferent font\u003c/c1\u003e.\n```\n\nfor the translators.\n\nThe attributes of certain HTML tags, such as the \"title\" attribute will have\nits value extracted as well as a string resource.\n\n## Comments\n\nIf you would like to place a translator's comment with a particular\nsection of text, you can do so with an HTML comment that starts with\n\"I18N\" like this:\n\n```\n\u003c!-- I18N this commment is extracted and sent along with the\n     resource that follows it. --\u003e\nThis is the text that is being commented upon.\n```\n\n## Links, References, and Footnotes\n\nYou can have references and links in your markdown as normal:\n\n```\nSee the code on [github](https://github.com/ilib-js/ilib-loctool-ghfm).\n```\n\nwhich becomes:\n\n```\nSee the code on \u003cc0\u003egithub\u003c/c0\u003e.\n```\n\nfor the translators.\n\nFor links, such as the above, the target URL of the link is not usually\ntranslated. However, you can override that for specific links with a\nspecial HTML comment directive:\n\n```\n\u003c!-- i18n-enable localize-links --\u003e\nSee the code on [github](https://github.com/ilib-js/ilib-loctool-ghfm).\n\u003c!-- i18n-disable localize-links --\u003e\n```\n\nIn this case, the URL `https://github.com/ilib-js/ilib-loctool-ghfm` will\nbe extracted as a separate string resource which can be localized independently,\npresumably to point to a localized version of the website.\n\nFor references with footnotes, the contents of the footnotes are usually not\ntranslated either if they consist only of URLs. Example:\n\n```\nThis text is [translated][tr].\n\n[tr]: http://www.non.translated.url/\n```\n\nHowever, you can override this for specific footnotes with the same HTML comment\ndirective:\n\n```\nThis text is [translated][tr].\n\n\u003c!-- i18n-enable localize-links --\u003e\n[tr]: http://www.non.translated.url/\n\u003c!-- i18n-disable localize-links --\u003e\n```\n\nIn this case, the url itself will be extracted as a separate string resource and will\nbe localizable.\n\n## Mappings\n\nThis plugin now supports mappings:\n\n```json\n{\n  [...]\n  \"settings\": {\n    \"markdown\": {\n      \"mappings\": {\n        \"**/foobar.md\": {\n          \"template\": \"[dir]/[basename]_[locale].[extension]\",\n          \"frontmatter\": [\"Title\", \"Description\"],\n          \"localeMap\": {\n            \"fr-FR\": \"fr\",\n            \"ja-JP\": \"ja\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nThe mappings allow you to match a particular path name and apply particular\nsettings to that path, such as an output path name template. The mappings are\nminimatch style.\n\nThe template follows the syntax for path name templates defined in the\nthe [loctool](https://github.com/iLib-js/loctool/blob/development/lib/utils.js#L1881)\nitself.\n\nThe frontmatter setting specifies an array of strings that represent the names\nof the fields in the frontmatter that should be localized. The frontmatter is\nparsed as a yaml file using the `ilib-loctool-yaml` plugin.\n\nAny fields not listed in the frontmatter list will be preserved but not be localized.\nIf frontmatter is set to \"true\" instead of an array,\nall fields will be localized. If frontmatter is set to \"false\", or if it is not\ngiven, then no fields will be localized.\n\nThe localeMap setting specifies the mapping between locales that are used\ninternally in the plugin, and the output locale that should be used for constructing\nthe file name of output files.\n\n## License\n\nThis plugin is licensed under Apache2. See the [LICENSE](./LICENSE)\nfile for more details.\n\n## Release Notes\n\n### v1.11.5\n\n- fixed incorrect imports of certain dependencies, which caused this\n  plugin to fail when they were updated\n\n### v1.11.4\n\n- Fixed a bug where code blocks introduced with triple backticks\n  were not properly parsed if they occurred right after some other\n  types of blocks. The work around is to add a blank link in front\n  of the code block which allows the parser to reset and behave properly\n- Fixed an problem with a \"dereferencing undefined\" exception that occurs\n  while printing out a warning about a previously caught exception, which\n  not only hides the first exception, but also causes loctool to abort\n  altogether!\n\n### v1.11.3\n\n- Fixed a bug where HTML-like tags that were indented and the only\n  thing on a line were not parsed correctly and caused infinite\n  recursion until the stack blew out\n- Fixed a bug where code blocks that start with an indented triple\n  backtick cause the markdown parser to skip every other item in an\n  ordered list and not extract its strings\n\n### v1.11.2\n\n- Updated dependencies\n- converted unit tests from nodeunit to jest\n\n### v1.11.1\n\n- Updated dependencies\n\n### v1.11.0\n\n- Now uses newest yaml parser which puts a hash of the source path name in the\n  key for each frontmatter field. This way, the Title field in different\n  md files will have different resource keys and therefore can be translated\n  separately.\n\n### v1.10.0\n\n- added localeMaps to the mappings\n\n### v1.9.1\n\n- fixed a bug where URLs in direct links were added to the new strings set\n  even when the localize-links directive was turned off. If the \"fully\n  translated\" flag was also turned on, then the plugin would think a file was\n  not fully translated because these links appear in the new strings set\n  and so it would not produce the localized version of the file.\n\n### v1.9.0\n\n- added the ability to localize URLs in direct links when the localize-links\n  directive is turned on\n\n### v1.8.4\n\n- fixed a bug where markdown embedded inside of flow HTML was not being parsed\n  properly. Flow HTML and markdown should be able to contain each other.\n\n### v1.8.3\n\n- fixed a bug where strings inside of flow HTML were not being extracted or\n  localized. Flow HTML is where the HTML tags span multiple lines. HTML that\n  was on a single line was already handled correctly--it is the multiple-lines\n  that threw off the parser. Example of flow HTML:\n\n```\n  \u003cspan class=\"myclass\"\u003e\n  This text is on a separate line.\n  \u003c/span\u003e\n```\n\n### v1.8.2\n\n- fixed a bug where the new and pseudo strings for the front matter were not\n  being generated properly\n\n### v1.8.1\n\n- fixed incorrect documentation (ie. the above text!)\n- mark files as not fully translated if there is pseudo translation\n\n### v1.8.0\n\n- added support for settings mappings\n- added support for parsing and localizing frontmatter fields\n\n### v1.7.2\n\n- Fix a bug where the pseudo locales were not initialized properly.\n  This fix gets the right set of locales from the project settings to\n  see if any of them are pseudo locales.\n\n### 1.7.1\n\n* Fixed an \"Unbalanced component error\" while parsing footnote definitions\n\n### 1.7.0\n\n* Added support for markdown footnotes using remark-footnote\n* Don't test on node 6 any more -- unit tests do not pass on node 6\n  because of a dependency which we can't really fix ourselves\n\n### 1.6.0\n\n* Added support for the \"fullyTranslated\" setting in the frontmatter if\nthe fullyTranslated setting is turned on in the loctool and the current\nfile has all of its strings fully translated.\n\n### 1.5.1\n\n* Updated dependencies so that this plugin can work on nodejs v6 still\n  without node-gyp problems.\n\n### 1.5.0\n\n* added a \"fullyTranslated\" setting for the markdown code. This makes sure\n  that if a file does not have all of its translations, then that file is\n  produced in the source language.\n    * Also produces a file in the project root called `translation-status.json`\n      that details which files were fully translated and which were not\n* Fixed a bug where markdown tables were not handled properly\n* Fixed a bug where inline code was not handled properly if it was the\nonly thing in the localizable segment. Inline code should only be\nlocalized if it is in the middle of or adjacent to localizable text.\n\n### 1.4.1\n\n* Fixed a bug where self-closed tags like \u003cbr/\u003e in markdown files were not handled properly,\ncausing exceptions that complained about syntax errors\n\n### 1.4.0\n\n- Add support for localizing links and link references.\n\nBy default, URLs are not localizable, as the majority are the same\nin all languages. Sometimes, however you want to be able to give a\ndifferent URL for each locale. With this new features, you can turn\non link localization.\n\nTo localize a link in the text, put a localize-links directive around\nit, which is an lint-style HTML comment. Example:\n\n```markdown\nThere are\n\u003c!-- i18n-enable localize-links --\u003e\n[fifty](http://www.example.com/)\n\u003c!-- i18n-disable localize-links --\u003e\nof them for sale.\n```\n\nThe text \"fifty\" is localized along with the rest of the sentence in the\nstring:\n\n```\nThere are \u003cc0\u003efifty\u003c/c0\u003e of them for sale.\n```\n\nNote the c0 tags denote where the link goes. The directives, being HTML\ncomments, are not included in the string to translate.\n\nThe URL itself appears as a separate string to translate.\n\nLocalizing a link reference is very similar. Surround the reference\ndefinition with a localize-links directive:\n\n```markdown\nThere are [fifty][url] of them for sale.\n\n\u003c!-- i18n-enable localize-links --\u003e\n[url]: http://www.example.com/ \"link title\"\n\u003c!-- i18n-disable localize-links --\u003e\n```\n\nThe link title for link reference definitions is included as a separate string\nto translate.\n\n### 1.3.0\n\n- The plugin now adds a translator comment/note for inline code so that the\n  translator can know what the text of the self-closing components is.\n- Minimum node version to run this plugin is now v10\n\n### 1.2.6\n\n- Add support for shortcut and full link references\n    - Shortcut references are converted back to full so that the title of the\n      reference can be translated to something different than the [possibly]\n      English label of the shortcut.\n\n### 1.2.5\n\n- Handle valueless HTML attributes properly\n\n### 1.2.4\n\n- The previous fix where HTML comments were not recognized and skipped properly\nwas only fixed for the parsing side of this plugin. Now it is fixed for the\nlocalization side as well.\n\n### 1.2.3\n\n- Fixed a bug where HTML comments were not recognized and skipped properly\nif there was whitespace/indentation before them in the source file.\n\n### 1.2.2\n\n- Fixed reference link support. If there is text in a reference link, then it will\nbe included in the text to localize.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filib-js%2Filib-loctool-ghfm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Filib-js%2Filib-loctool-ghfm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filib-js%2Filib-loctool-ghfm/lists"}